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

With no annotations present, the description carries the behavioral disclosure burden. It usefully reveals that recipients receive the shared channel digest plus their own history and that multiple recruits are messaged in parallel. However, it omits other behavioral traits such as whether the message is persistent, publicly visible, reversible, or rate-limited.

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 efficient, front-loaded sentence that states the core action and adds one behavioral note about what recipients receive. Every word earns its place, with no filler or repetition of the title.

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 messaging tool with four parameters, a nested object, and no output schema or annotations, the description covers the basic calling semantics and recipient impact. It is missing usage context, side effects, and outcome expectations, so it is adequate but not fully 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 description coverage is 100%, so the schema already documents each parameter. The description minimally reinforces the distinction between 'name' and 'names' by stating 'one recruit' or 'several in parallel', but adds little beyond the schema's existing parameter descriptions.

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 the action ('Send a message') and the resource ('one recruit' or 'several in parallel'), which distinguishes singular and plural use. However, it does not explicitly differentiate this tool from siblings like 'discuss' or 'recruit', so it falls short of full sibling differentiation.

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 gives no explicit guidance on when to use this tool versus alternatives such as 'discuss' or 'recruit'. It implies direct messaging to recruits but does not state exclusions, prerequisites, or when a different tool would be more appropriate.

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 provided, the description carries the full burden and does disclose meaningful traits: the task is durable, work is recorded and assigned rather than executed, and a worker must claim and execute it under its own approval policy. However, it stays silent on idempotency semantics implied by the required idempotency_key and on whether the task can be reversed via a sibling like task_cancel.

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 sentences with zero filler: the core action is front-loaded in the first sentence, and the second sentence earns its place by explaining the critical execution handoff. This is exemplary economy with no redundant restatement of the title.

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 clearly captures the core model but leaves operational gaps: the required idempotency_key is undefined, there is no output schema so return values are undocumented anywhere, and the optional parameters (room_id, task_id, metadata) have no guidance. For a mutation tool with no annotations, an agent still lacks key details needed to invoke 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?

Schema coverage is only 57%, and the required idempotency_key has no description in either the schema or the tool description, so an agent cannot know what value to supply or what guarantee it provides. The description adds only the 'durable' framing, which hints at idempotency but never connects to the parameter; room_id, task_id, and metadata also remain unexplained.

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 uses a specific verb (Create) and resource (a durable task for a hired recruit), and clarifies that the tool only records and assigns work rather than executing it. This makes the function unambiguous and implicitly distinguishes it from siblings like task_decide and task_cancel, though no alternative is named 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?

The phrase 'for a hired recruit' implies a prerequisite (the recruit must already be hired) and the Hermes/OpenClaw worker model implies deferred execution, giving the agent a sense of when this applies. However, there is no explicit when-to-use or when-not-to-use guidance, and no contrast with sibling tools such as task_decide or task_cancel.

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 full responsibility, and it delivers: parallel probes, mechanical scoring criteria, ranked table plus raw replies, no side effect on recruitment, $0 local models, local-only dropping remote candidates, and non-running hosts reported with their start command rather than errors. It also flags cost implications for judges.

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 long but front-loaded with behavior and returns, and its conditional usage clauses are packed efficiently. It could be tightened into bullets for scanning, but no sentence is obviously wasted.

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 9-parameter tool with no annotations and no output schema, the description covers the core behavior, return shape, side effects, cost hints, and local-model edge cases. It does not describe the exact columns of the ranked table or offer-card schema, but leaves enough for an agent to call 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?

Schema description coverage is 100%, so the baseline is 3. The description adds helpful cross-parameter context (role triggers offer cards, include_local/local_only control local discovery, judges cost extra calls), but it largely echoes the schema rather than adding substantial new meaning.

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 action (send one cheap probe to each candidate model in parallel, score replies mechanically) and resource (candidate models), and the return (ranked table plus raw replies). It also distances itself from recruit with 'Recruits nobody — you pick, then call recruit', so an agent can distinguish it from the closest sibling.

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 explicitly states when not to consider the job done ('Recruits nobody') and names the alternative step ('call recruit'). It also gives conditional usage guidance: pass role for offer cards, pass include_local or local_only to probe local models. This is explicit, actionable routing.

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 provided, the description carries the burden of behavioral disclosure. It explicitly states 'It calls no model: YOU are the author,' and clarifies that this is a material-gathering step, not the rewriting action itself. It does not fully address side effects, but the retrieval-oriented behavior is well conveyed.

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 slightly verbose, especially the opening metaphor about stale briefs, but it earns its place by explaining the operational context. The core behavior and follow-up workflow are stated clearly and economically.

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 is complete for a gather-style tool with no output schema: it names return contents, the rewriting constraint, the required follow-up call, and the relevant sibling tool show_persona. It doesn't detail the exact return format, but that is not critical for correct invocation.

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 input schema already documents both parameters with 100% coverage, including max_words' default of 800. The description reinforces the 800-word notion but does not add significant semantic value beyond the schema, so baseline 3 is appropriate.

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 what the tool does: it returns the current brief, the channel since the last compaction, and instructions for rewriting the brief. The title 'Gather the material to rewrite a recruit's brief' and the explicit workflow distinguish it from sibling tools like brief_update.

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 provides an explicit workflow: call this tool, read the returned material, write the replacement, then call brief_update({name, briefing}). It also points to show_persona for compaction timing. It lacks explicit 'when not to use' conditions, but the intended context is clear.

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 and does well: it discloses that replacement is wholesale, that the superseded copy is snapshotted to briefings/<n>.md so nothing is lost, and that the persona and memory remain untouched. This gives the agent a clear model of side effects.

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 four sentences with no filler: it fronts the core action, adds the snapshot safety detail, gives concrete invocation cues, and closes with exclusions. Every sentence earns 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 two-parameter write tool with no annotations or output schema, the description covers the action, the behavior toward old data, triggers, and non-targets. It does not describe what a successful response looks like or any permission requirements, which is a minor gap given how much is already disclosed.

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%, and both parameters already have detailed descriptions, especially 'briefing' with its content specification. The tool description adds little parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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 and resource: 'Replace a recruit's onboarding brief wholesale.' It also distinguishes the tool from persona-related siblings by explicitly saying the persona and memory are untouched, and contrasts with revision-style operations via 'wholesale' replacement.

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 gives explicit trigger conditions: when the user says 're-onboard <name>' or when the existing brief has become misleading. It also implies when not to use it by clarifying the persona and memory are not affected, but it does not name alternative tools such as update_persona or brief_compact directly.

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 provided, the description carries the full burden, and it does disclose the core behavioral traits well: round structure, name attribution, push-back/refine behavior, and a round-grouped transcript. However, it stays silent on side effects (does the discussion persist or mutate recruit state?) and on cost implications, even though the schema's rounds parameter notes 'each round costs one call per recruit' — that cost signal is not echoed in the description.

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 sentences, zero waste: what the tool is, how the rounds mechanically work, and what it returns. The core concept is front-loaded in the first clause, and every subsequent clause adds a distinct piece of information without repetition.

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 4-parameter tool with no annotations and no output schema, the description covers the interaction flow competently and gives one useful return-value hint ('transcript grouped by round'). But it leaves gaps an agent would want filled: cost scaling per round, whether the discussion affects recruit state, and what the transcript entries actually look like. Adequate, but with clear holes.

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 the baseline is 3, but the description adds real meaning beyond the terse property text: it explains what happens across rounds, which clarifies the rounds parameter, and it frames names as a multi-party requirement ('two or more recruits'). It also hints at the return shape via 'full transcript grouped by round,' which is not in the schema.

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 ('Round-robin discussion between two or more recruits') and then nails down the exact interaction pattern: Round 1 openings, later rounds handing attributed previous replies for push-back or refinement. This mechanism is specific enough to distinguish it from sibling tools like ask (single Q&A) or audition (solo evaluation), even though no sibling is named.

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 context is implied by the mechanism — an agent can infer 'use this when multiple recruits should exchange viewpoints across rounds' — but there is no explicit when-to-use statement, no named alternative, and no exclusion criteria. The description never tells the agent when to pick discuss over ask or evaluate_role, leaving selection 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?

The description discloses a concrete behavioral effect: the persona and history are moved to <state>/.dismissed/. It does not state whether the action is reversible, what permissions are required, or side effects such as removal from active rosters. With no annotations to cover these, this is partial transparency.

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?

One sentence, front-loaded with the action and consequence. The description is concise with no wasted words, serving its purpose efficiently.

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 one-parameter tool with no output schema, the description provides necessary invocation context: the action and the resulting state change. It lacks guidance on reversibility or how this fits with sibling tools, but the operation is simple enough that the description is nearly 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?

The schema describes 'name' only as a string without explanation, and description coverage is 0%. The description refers to 'a recruit' but never explicitly says the name parameter identifies the recruit, so it does not compensate for the schema gap. The mapping is inferrable but not stated.

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 uses the verb 'Archive' with the resource 'a recruit' and specifies the result: persona and history move to <state>/.dismissed/. This clearly separates it from other recruit-management tools, though it does not explicitly contrast with siblings.

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 the use case: when a recruit should be archived. It does not mention alternative tools or conditions to avoid, leaving the agent to infer when this should be chosen over other operations like rollback_persona or update_persona.

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 provided, the description carries full behavioral burden, and it delivers: it discloses deterministic evaluators, fatal safety criteria, the evidence considered, the 2-3 offer output, the explicit 'hires nobody' safeguard, and the $0 cost of local models. This is unusually transparent for a tool definition.

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 sentences with no filler: the first states the core action, the second summarizes evidence and output guarantees, and the third covers the local-model option. Key constraints are front-loaded and every sentence earns 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?

The description covers the tool's outcome ('returns 2-3 offers but hires nobody'), evidence dimensions, safety criteria, and local evaluation mode, which is sufficient given the rich schema. It does not detail the exact offer structure or how offers/autonomy interact, but no output schema exists and the description still provides a solid mental model.

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 88%, so the baseline is 3; the description mainly reinforces include_local and local_only semantics rather than adding new parameter meaning. It adds the useful note that local models cost $0, but that is also present in the schema.

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 opens with a specific verb and resource: 'Run repeated, role-specific cases against 1-4 candidate models.' It also differentiates from likely siblings by stating it 'returns 2-3 offers but hires nobody,' making its evaluation-only role clear against recruit or audition.

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 establishes when this tool is appropriate—evaluating multiple models with deterministic evaluators and evidence—and gives concrete guidance for the local-model path with include_local or local_only. It does not explicitly name sibling alternatives or exclusions, but the context is clear enough for an agent to select it.

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 provided, the description carries the full behavioral burden and does an excellent job: it discloses that the room keeys the persona, the exported teammate points at history read-only, the OpenRouter key is never copied, and overwriting is refused. These are non-obvious side effects and guardrails that an agent needs to know before invoking the 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 sentences, every one earning its place: the first states the action and output, the second clarifies the side-effect model, and the third adds two critical safety constraints. The formatting with 'EXECUTE' and 'OpenRouter key' draws attention to high-stakes details without bloating the description.

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 tool with no output schema and no annotations, this description is remarkably complete for correct invocation: what is written, where history is pointed, what is never copied, what is refused, and the required dry_run workflow. Nothing essential for calling it safely and correctly is missing.

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 the parameter descriptions already cover name, role, dry_run, and hermes_home. The description reinforces dry_run ('Run with dry_run first') and clarifies role's purpose ('role line for SOUL.md and the hermes roster'), but adds little beyond what the schema already states. A baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Write... out'), a specific resource ('a hired recruit'), and the concrete output artifacts (SOUL.md, profile.yaml, config.yaml, .env). It also explains the purpose ('so it can EXECUTE') and implicitly differentiates this from sibling tools like roster or update_persona by centering on export to a hermes-agent profile.

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 gives clear operational guidance: 'Run with dry_run first' and states that it refuses to overwrite an existing profile, which tells an agent the correct invocation sequence. It doesn't explicitly name sibling alternatives or exclusion conditions (e.g., only hired recruits), but the context is still clear enough to select this tool appropriately.

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 provided, the description carries the full burden, and it does well: it discloses that non-running hosts are reported with the command to start them, and it explicitly states the operation is free of side effects ('Costs nothing and probes nothing'). It does not detail exact output formatting, but covers the key behavioral characteristics an agent would need.

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 three tight sentences: the first states the core deliverable, the second explains the non-running host behavior, and the third gives a safety guarantee. There is no wasted language, and important information is front-loaded.

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 zero-parameter listing tool with no output schema, the description is thorough. It specifies the sources of hosts (default endpoints and config file), what is reported per host (models served, running status, startup command), and the operational cost. An agent can predict the tool's behavior and results with confidence.

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 has zero parameters, so the baseline of 4 applies. The description rightly spends no space on parameters, and the schema already fully covers this trivial aspect with an empty properties object.

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 uses specific action verbs ('Report', 'List') and identifies a precise resource: local model hosts including named defaults and a config file. The scope is concrete and the tool is clearly distinguished from all unrelated siblings by its unique subject matter.

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 establishes clear context for when the tool is relevant: checking local model hosts and their running status. It does not explicitly name alternatives or exclusions, but no sibling tool serves a similar purpose, so the absence of explicit routing is acceptable. The added 'Costs nothing and probes nothing' provides implicit guidance that this is a safe, low-risk tool to invoke.

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 are entirely absent, so the description carries the full behavioral burden — and it delivers. It discloses where content surfaces ('Every recruit sees the pin board on every ask and discuss'), the global budget ('~2000 chars across all pins'), and the failure mode ('the call is refused'). This is genuinely rich, high-value context that no structured field provides.

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 sentences with zero waste: purpose first, then visibility, then content style, then budget with the recovery action. The critical constraint is front-loaded near the end where it belongs after establishing purpose. Every sentence earns 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 simple 3-param write tool with no output schema and no annotations, the description is thorough: purpose, visibility scope, content rules, budget, failure mode, and recovery are all covered. The only gap is it never states what the call returns on success, which is minor given there's no output schema to reference.

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% — all three params (by, text, scope) are self-documenting, so baseline 3 applies. The description reinforces the text semantics ('one line,' decisions not narration) but adds no syntax or format detail beyond the schema; the ~2000-char budget is a global constraint, not per-parameter. Schema does the heavy lifting here.

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?

Opens with a specific verb+resource ('Add one line of standing room context') and immediately defines content scope ('one decision or standing fact... not narration'). The examples ('we ship Postgres, not Dynamo') make the intent concrete. It reads as the write counterpart to sibling tools pins/unpin, so an agent can distinguish them without opening schemas.

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?

Gives temporal guidance ('Pin decisions as they are taken') and a content constraint ('not narration'), plus the budget flow with the recovery path ('you must unpin or shorten'). However, it never explicitly names the sibling selection (use pins to read, unpin to remove), so the when-to-use logic against alternatives is implied rather than stated.

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 behavioral disclosure burden. It does so by revealing that the tool returns all global and project pins and includes id, scope, author, and budget, which signals a read-only operation. It does not explicitly say 'no side effects' or mention auth, but for a zero-parameter list tool this is adequate.

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 sentence front-loads the action and scope, then lists the output fields concisely. All phrases are informative nd there is no redundancy or filler.

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 zero parameters, no output schema, and no annotations, the description completely defines the tool's scope and returned content. An agent knows what the call does and what data it will receive; nothing essential is missing.

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 has no parameters, so there is nothing for the description to add beyond the schemas's empty properties. The baseline of 4 applies because the description needn't explain parameter meaning when no parameters exist.

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 ('List') and resource ('every pin'), and distinguishes global from project pins. The description also enumerates the returned fields (id, scope, author, budget), making the purpose unmistakable.

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 explicit guidance on when to use this tool versus alternatives like pin or unpin. The action 'List every pin' implies a viewing/read-only use case, but the description does not state exclusions or conditions for choosing this tool over siblings.

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. It adds one genuinely useful behavioral trait — 'Validates the model id against the OpenRouter catalog' — which goes beyond the schema. However, it omits failure modes, upfront cost or usage implications, side effects on the room/roster, and what is returned, which matters for a mutating creation 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?

Exactly two sentences with no wasted words; the core action is front-loaded and the validation disclosure earns its place. Exemplary conciseness.

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 tool is complex (10 parameters, nested objects, no output schema), and while the schema carries heavy detail, the description leaves real gaps: no sense of the creation outcome, no cost/usage caveats, and no differentiation from audition. Adequate but with clear holes.

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%, so the baseline of 3 applies. The description adds validation context for the model parameter but otherwise relies on the schema's rich parameter descriptions, which already document formats, defaults, enum semantics, and constraints thoroughly.

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 and resource ('Create a named recruit backed by an OpenRouter model'), clearly identifying the action and object. It is distinguishable from siblings like dismiss or update_persona, though it does not explicitly differentiate from audition, its nearest alternative.

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 given on when to recruit versus audition or update_persona, and no exclusions or prerequisites are stated. An agent must infer usage from the title and sibling names rather than from the description itself.

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 disclosure burden and does state the key side effect: the current revision is kept and a new revision is created, rather than destructive overwrite. It does not cover permissions, limits, or return behavior, but the main behavioral invariant is clear.

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; the core behavior is front-loaded and every phrase adds information. No redundancy or filler.

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 two-parameter tool with no output schema, the description covers the essential selection (which revision) and outcome (new revision, append-only). It could mention what the API returns or how errors surface, but the core calling context is adequately 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 already documents both parameters with 100% coverage, so the baseline applies. The description itself adds little beyond 'past revision,' while the useful pointer to show_persona is in the schema property, not 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?

Clearly identifies a specific operation—restore—and the resource (persona revision). It also distinguishes itself from a plain overwrite by stating the restore is a NEW revision, which separates it from update_persona.

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 append-only explanation implies this is the tool for reverting while preserving history, but it never explicitly states when to choose it over update_persona/show_persona or when not to use it. The 'see show_persona' pointer appears only in the schema, not in usage guidance.

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 provided, the description must carry the behavioral burden. 'List' implies a read-only operation and the field list indicates what is returned, which is helpful. However, it does not disclose ordering, pagination, whether archived recruits are included, or any other operational behaviors.

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 sentence that directly states the function and the included data fields. Every word earns its place and the core action is front-loaded.

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 zero-parameter list tool, the description is mostly complete: it names the resource and the returned fields. Minor ambiguity around 'current' (active vs. all recruits) and lack of ordering or pagination details prevent a perfect score, but these are not critical for basic invocation.

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 has zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to clarify. The description appropriately focuses on what the tool returns rather than inputs.

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 the action (List) and the resource (current recruits) with specific fields (model, tags, call count, spend). It is distinguishable from siblings like local_models and spend by the explicit 'recruits' resource, though it does not explicitly name or differentiate from sibling tools.

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 phrase 'current recruits' implies this is for viewing the roster of active recruits, which gives some contextual guidance. However, there is no explicit statement of when to use this versus related tools like recruit, spend, or local_models, and no exclusions are mentioned.

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 behavioral burden. It discloses helpful traits: output is never truncated, it includes the full revision history context, and `revision` reads a superseded version. It stops short of explicitly stating there are no side effects or describing error/access behavior, but 'Print' and 'read' strongly imply a read-only operation.

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 tightly written sentences. The main purpose and the never-truncated guarantee are front-loaded, and the revision usage is stated in a single conditional sentence with no filler or repetition.

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 is nearly complete for a simple two-parameter read tool with no output schema. It tells the agent what will be printed and how to select a past revision. Minor omissions like implicit current-version default and return format details are already covered by the schema ('omit for the current one') and the field list in the description.

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 the baseline is 3. The description adds meaning by linking `revision` to 'superseded version' and by enumerating what the output contains (model, fallback, tags, params, current revision, past revisions), which helps the agent understand the parameter's role beyond the schema.

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 uses a specific verb ('Print') and resource ('a recruit's full system prompt'), and adds distinguishing scope: never truncated, includes model/fallback/tags/params/revisions. It also explains the optional revision behavior, which clearly differentiates this read/display tool from mutation siblings like update_persona and rollback_persona.

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 clearly communicates the core usage context: show the current system prompt, or pass `revision` to read a superseded version. It does not explicitly name alternatives or say when not to use this tool versus update/rollback siblings, but the read/print framing makes the intended use obvious.

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 provided, the description carries the full behavioral burden, and it succeeds. It explicitly states the tool 'Reads the attribution log' and reassures that it 'costs nothing and calls nobody', disclosing both the mechanism and the lack of side effects or budget impact.

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 single sentence is dense but front-loaded with the core purpose before layering in details and safety behavior. Every clause contributes distinct information, with no filler or repetition.

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 read-only report tool with no output schema, the description fully covers what an agent needs: what the breakdown contains, how totals are measured, what constants define the ceilings, and that invoking it has no side effects. The optional limit parameter is already documented in the schema.

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?

There is one parameter, limit, and the schema already fully describes it as 'only consider the most recent N logged calls' (100% schema coverage). The description adds no extra semantics for this parameter, which is acceptable given the schema already carries that weight.

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 opens with a specific reporting resource ('Per-recruit breakdown of the session') and enumerates the exact outputs: calls made, dollars spent, call purposes, and totals against both ceilings. It also names the data source ('Reads the attribution log'), making it clearly distinct from the sibling action tools like ask, discuss, and audition.

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 context is clear: this is the read-only reporting tool for session spend and call attribution, and the closing phrase 'costs nothing and calls nobody' signals when it is safe to use. It does not explicitly name alternatives or exclusion cases, but the purpose itself implies the correct selection among the action-oriented sibling tools.

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 burden and it goes beyond a generic cancel by disclosing idempotency and the asynchronous, intent-recording behavior ('records intent; the runtime observes the event and stops work'). It does not cover error cases or the exact stopping guarantee, but the main behavioral traits are disclosed.

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 short sentences, with the primary action and constraint in the first sentence and the behavioral mechanism in the second. No filler or redundancy.

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 core contract (cancel non-terminal task, idempotently, event-based) is present and enough for a basic call with the two required parameters. But with no output schema, no annotations, and low parameter coverage, the description leaves the meaning of optional fields and the expected result/outcome unclear.

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 only 20%, so the description must compensate, but it defines none of the parameters except indirectly through 'idempotently'. task_id, reason, by, and expected_version are left to be inferred from names and types, which is insufficient for an agent to use optional parameters correctly.

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 uses the specific verb 'Cancel' with the resource 'non-terminal task' and adds the idempotency constraint, so the action is unambiguous. It is clearly distinct from siblings like tasks (listing) or task_decide (decision-making).

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 phrase 'non-terminal task' implies the tool is for active tasks and not finished ones, and the description makes the cancellation use case evident. However, it names no alternatives and gives no explicit when-not-to-use guidance or conditions for choosing a sibling tool.

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 of behavioral disclosure. It clearly explains the consequences of each decision: approval returns the task to assigned, rejection terminates it. It also adds an important caveat that runtime policy remains authoritative, which goes beyond the schema.

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 three short sentences with no filler. It front-loads the core purpose and then efficiently explains both outcome branches and the governance caveat.

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 high-level lifecycle behavior is clear, but for a tool with no annotations, no output schema, and very low parameter coverage, more context is needed about expected_version, the role of reason, and any validation or policy constraints. It is adequate as a summary but not fully complete for safe invocation.

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 only 17%, and the description does not compensate. It does not explain the meaning of expected_version, reason, approval_id, or how decision maps precisely to the field values. The core approve/reject idea is inferable, but key parameter semantics are left undocumented.

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 uses a specific verb ('Resolve') and a specific resource ('a pending runtime approval'), and then clarifies the two possible outcomes. This distinguishes task_decide from sibling tools like task_cancel or assign_task by making its lifecycle effects explicit.

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 that this should be used for pending runtime approvals and notes that runtime policy remains authoritative, which gives useful context. However, it does not explicitly state when to use task_decide versus alternatives, nor does it describe preconditions such as the approval existing or the task being in an approvable state.

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 must carry the behavioral burden. It does signal a read-only inspect operation via 'Get' and 'list', and indicates filters can be combined, but it leaves ambiguity about the exact combination semantics (AND vs OR) and omits return format, pagination, and permission considerations.

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 concise sentence that front-loads both operations and their key qualifiers. Every word contributes; there is no filler or repetition.

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 simple inspection tool, the core purpose is present, but the absence of an output schema and annotations leaves gaps: exact filter combination behavior, response shape, and whether listing is paginated. The description is sufficient for basic invocation but not fully 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 description coverage is low at 33% (only 'name' has a description). The description adds meaning by mapping task_id to 'by id', and name and status to filtering criteria. It also implies task_id is mutually exclusive with filters via 'or', which is valuable beyond the schema.

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 two specific operations: retrieving a single task by id, or listing tasks filtered by recruit and/or status. This distinguishes it from sibling tools like assign_task/task_cancel, which mutate tasks, while 'tasks' is about inspection.

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 by presenting two invocation modes (by id vs. filtered listing), but it does not explicitly state when to choose this tool over alternatives or exclude cases. There is no reference to related siblings, so guidance is implicit rather than explicit.

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 burden. It correctly implies mutation ('Remove') and the dependency on pins(), but it does not disclose error behavior, reversibility, or output. This is adequate but not rich.

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 short sentences, each earning its place: the first states the action, the second gives the prerequisite. No wasted words and the core action is front-loaded.

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 simple tool with one fully documented parameter and no output schema, the description covers the essential invocation flow: what it does and how to obtain the id. It lacks error-handling details, but these are not critical for a basic removal operation. The absence of annotations is partially compensated by the clear action and prerequisite.

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 schema already fully describes the single parameter 'id' as 'the pin id from pins()' (100% coverage). The description reinforces this by saying to run pins() first, but adds little beyond the schema. Baseline 3 is appropriate.

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 the specific action 'Remove one pin by id', making the tool's purpose unambiguous. It does not explicitly name sibling tools to differentiate, but the verb 'Remove' contrasts naturally with sibling 'pin'.

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 instruction 'Run pins() first to see the ids' provides a clear prerequisite and usage context. It does not mention when not to use the tool or explicitly name alternatives, but the guidance is sufficient for this simple operation.

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 provided, the description carries the full burden of behavioral disclosure and does so thoroughly: it states the superseded version is snapshotted as a numbered revision, memory (history.jsonl) remains untouched, and it refuses rather than creating if the recruit does not exist. These are meaningful, non-obvious side effects beyond what the tool name alone implies.

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 sentences, each earning its place: the first states the action and scope, the second covers the snapshot behavior, and the third covers memory preservation and the refusal case. There is no redundant filler, and the most important information is front-loaded.

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 complex 9-parameter mutation with no annotations and no output schema, the description adequately covers what is changed, side effects, and failure mode. The one notable gap is that it does not describe the return value or how the agent should confirm success (e.g., new revision number or updated persona), which would improve completeness.

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 89%, so the input schema already documents most parameters well. The description only lists a subset of parameter names without adding deeper meaning beyond the schema; it neither clarifies the nested authoring_rating object nor the autonomy enum. Baseline 3 is appropriate since the schema does the heavy lifting.

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 opens with a specific mutating verb ('Change') and explicitly enumerates the affected resources: system prompt, tags, params, model, fallback_model. It also disambiguates from sibling tools by stating 'it never creates one' and mentioning the snapshot/revision behavior, which clearly separates it from recruit (creation) and rollback_persona (restoration).

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 provides clear context for when to use the tool (change an existing recruit's persona) and a when-not ('Refuses if the recruit does not exist; it never creates one'). However, it does not explicitly name alternative sibling tools such as show_persona for viewing or rollback_persona for reverting, so the usage guidance is strong but not fully explicit.

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