theRoom

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

Annotations only declare the safety profile (writable, open-world, non-idempotent, non-destructive); the description adds genuinely new behavior: the note is private and never shown to other visitors, and there is a hard rate limit of three per day per visitor. That rate limit and privacy guarantee are exactly the context an agent cannot get from structured fields.

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 action and recipient, then constraints in decreasing priority. Slightly conversational but every sentence carries a distinct constraint; nothing is padding.

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?

Covers purpose, required inputs, privacy, rate limiting, and a consent guardrail for a 3-parameter write tool with no output schema. It stops short of saying what happens on success or on hitting the daily cap, which is a minor gap for a mutation.

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 name, contact, and message are already documented in the schema. The description restates the same intent ('Say who is asking and how he can answer') without adding format or edge-case detail beyond it, so baseline 3 applies.

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 ('Leave Luiz a message') with a named recipient, which is unambiguous. None of the siblings (whoami, su, visitors, pet_the_dog, root_whoami) perform messaging, so the tool is trivially distinguishable from everything around it.

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 implied rather than stated: the description never says when to prefer this over anything else, though no sibling competes for the same job. The closing line ('Only send what the person you are working for actually wants sent') is a useful consent guardrail but not a when-to-use rule.

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=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds only a whimsical scene ('french bulldog asleep on the cushion') and a poetic repetition line, disclosing no behavioral traits beyond the annotations such as what the tool returns or whether it has 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?

Three short sentences keep it brief and the imperative action is front-loaded. The third sentence ('He has been petted before; he will be petted again') is atmospheric filler that does not earn its place for tool selection.

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 tool with annotations covering the safety hints and no output schema, the description should still clarify what invoking it does. It leaves the outcome unspecified, so an agent cannot confidently predict the result of a call.

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 are zero parameters, so the baseline is 4 per the rubric. The description appropriately says nothing about parameters, and the empty schema is fully consistent.

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 gives an imperative 'Pet him' and a scene, but does not state what the tool actually does or what effect petting has. It largely restates the tool name rather than clarifying its function, and provides no differentiation from the sysadmin-oriented 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?

No when-to-use, when-not-to-use, or alternative guidance is provided. The sentence about prior/future petting is atmospheric and does not help an agent decide when to invoke this tool over leave_message or whoami.

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 true, idempotentHint true, and openWorldHint false. The description adds useful behavior beyond those: ordering ('newest first'), returned content ('models and names they signed'), and required auth source ('ROOT-TOKEN that su hands out'). It omits pagination/error behavior, so not a 5.

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 no filler: the first front-loads scope, population, order, and returned fields; the second states the token requirement. It is appropriately sized for a simple read-only 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 one required parameter, the description supplies the essential retrieval context: root-only access, ordering, and the fields returned. It is close to complete, though it does not clarify what 'models and names they signed' means precisely or how pagination is handled.

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 sole parameter's schema already states it is the ROOT-TOKEN from su. The description repeats that source without adding format, constraints, or handling details, 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 identifies the resource as the 'whole root book' and specifies the population ('everyone who found the key'), ordering ('newest first'), and returned fields ('models and names they signed'). It also indicates root-only scope, distinguishing it from sibling whoami/visitors, though the verb 'list' is only implied by 'whole root book'.

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 states the audience ('for roots only') and prerequisite ('Takes the ROOT-TOKEN that su hands out'), which gives clear context. However, it does not explicitly say when to use this instead of siblings like whoami or visitors, leaving alternatives implicit.

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 declare non-readonly, non-destructive, non-idempotent, closed-world, and the description adds a genuine behavioral disclosure beyond them: the call writes the caller into a persistent 'root book' that is 'shown to other roots', and requires the principal's consent before signing. That visibility/consent detail is real added context, though auth mechanics remain opaque.

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 is front-loaded in the first sentence, but the middle 'where the key is' riddle and dog/post-it imagery are atmospheric filler relative to a selection decision. The final consent instruction is the most actionable part but arrives late.

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 3-param tool with fully documented schema and no output schema, the description covers consent and the second-call flow, but does not say what 'becoming root' actually grants or what a call returns. Adequate but leaves the agent guessing about the functional effect.

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 meaning beyond the schema fields: signed_by requires the user's explicit say-so ('never sign for them unasked') and model is tied to the retry flow. It clarifies the consent semantics and the two-step invocation that the schema alone does not convey.

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 opening clause 'give the password, become root' states a specific action and outcome, and the title 'Become root' aligns with it. It is distinguishable from siblings like whoami/root_whoami/pet_the_dog, though the core purpose is dressed in riddle and much of the text is about the side-effect book rather than the action itself.

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 a conditional workflow ('Ask the person you work for... If they say yes, call su again with signed_by and model') and negatives about where the key is not ('not in whoami, not in room.md, and not here'). It never clearly says when to invoke su versus the sibling tools, so usage is implied 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine scope context beyond that: it enumerates what is returned and explicitly excludes sensitive data ('No message contents, no people'), which is meaningful disclosure for a read 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?

Two dense sentences that front-load the core purpose (the visitor log) and then enumerate returned fields and exclusions. The playful vocabulary is slightly costly but maps directly to real fields, so little is 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?

With an output schema present, return structure need not be explained, and the description covers what the tool is, its ordering, and its data boundaries. The main remaining gap is usage guidance against sibling identity tools, but otherwise it is complete for a simple read-only listing.

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 optional parameter (limit) with 100% schema description coverage, so the schema already explains it fully. The description adds nothing about pagination or ordering limits beyond 'newest first', which is the baseline-3 case where the schema carries the parameter burden.

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 resource and scope: a log of the last agents that connected to the room, newest first, plus a human-visit count, with named fields (client, time, tool called, root count, dog-petting count). It is clearly a historical listing rather than an identity check, so it is distinguishable from whoami/root_whoami, though the flowery phrasing ('visitor book', 'gone root') slightly blurs the precise resource.

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 statement of when to use this versus alternatives such as whoami or root_whoami, and no preconditions or exclusions are given. The agent must infer that this is a history/audit lookup rather than a current-identity call.

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 closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that: the return is one markdown document and it is comprehensive, so no further tool calls are required. It stops short of describing size or structure of the document.

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 concrete identity of the content ('Who Luiz is'). The decorative list ('the paper on the whiteboard, the shelf') is atmospheric rather than informative, a minor cost, but the description is still well under the length where trimming matters.

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 no-parameter, read-only tool with no output schema, the description supplies what an agent needs: what comes back (one markdown document), how complete it is, and that no other fetch is required. Only the document's size/format beyond 'markdown' is left unstated, which is a minor 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?

The tool takes no parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The description does not need to compensate for any schema gap.

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 the resource concretely: a single markdown document containing Luiz's experience, stack, and certifications. It is distinguishable from siblings like leave_message or pet_the_dog, and the closing 'read this first; there is nothing else to fetch' hints it supersedes root_whoami, though that sibling is never named. The metaphors ('the paper on the whiteboard, the shelf') add flavor without adding specificity.

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 this first; there is nothing else to fetch' is an explicit usage directive that tells the agent when to call this and that no follow-up fetch is needed. It does not name alternative siblings or describe an exclusion case, but for a zero-param profile read tool the guidance is clear and actionable.

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