core.blue

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely new context beyond annotations: that the output is formatted to paste into a report and includes liveness status plus suggested next calls, which tells the agent what the payload looks like behaviorally.

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 dense sentence that front-loads what the tool is and closes with the actionable 'Call this first' directive. Every listed content item earns its place, though the sentence is long and could be split for readability.

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 values need not be described in prose, and the description still summarizes the payload's contents and role. Combined with rich annotations and a no-param signature, the definition gives the agent enough 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. Schema coverage is 100% and no parameter semantics are needed.

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 concretely what the tool returns: a one-paragraph product summary, live/not-live status, what to call next, and every manual topic with a summary. That is specific enough that an agent can tell it is an orientation/index tool, distinct from read_topic or pricing, though it does not name those siblings explicitly to sharpen the contrast.

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 closing directive 'Call this first' is an explicit when-to-use instruction that places the tool at the start of a session. It does not state when-not to call it or name alternative tools, so it falls short of a full when/when-not/alternatives treatment.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds real value by scoping the destruction to 'the house and everything in it' and noting the resource is released for the next agent. It does not address repeat calls on an already-closed sandbox, which is the one behavioral gap given the idempotent hint.

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, front-loaded with the primary destructive action before the secondary feedback request. The enumeration of the four feedback questions partially duplicates the schema descriptions, which is the only minor waste.

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?

An output schema exists so return values need no explanation, and the description covers the destruction scope and the feedback side-channel. An agent has what it needs to call it correctly; only edge cases like an invalid or already-used lease are unaddressed.

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 all five parameters including the four optional feedback strings are already documented. The description restates those four fields rather than adding syntax, format, or constraints beyond the schema, 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 ('End your sandbox now') and immediately names the consequence ('the house and everything in it is deleted'). It is unmistakably distinct from the sibling open_sandbox, so an agent can select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly frames the end-of-session moment ('free for the next agent') and explicitly routes feedback through this call instead of the sibling leave_feedback ('answer the four questions of leave_feedback here as well'). It does not state exclusions or what happens if the lease is already closed, so it stops short of a full when/when-not treatment.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower; the description still adds a concrete rate limit ('no more than once an hour') and notes it 'says what to do next' and returns the address once the house exists. Auth requirements and failure behavior for an invalid ticket are not disclosed, keeping it from 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?

Three sentences, front-loaded with what the tool returns and the possible states, with the rate limit last. The state enumeration is long but directly useful; otherwise little waste.

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?

An output schema exists, so return structure need not be spelled out, yet the description still summarizes the meaningful return content (states, next action, address) and adds the polling constraint. For a single-parameter read tool with annotations, this is close to complete; only error/edge behavior for an unknown ticket is unaddressed.

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% for the single parameter and the schema already documents ticket_id as 'the ticket id returned by request_house'. The description adds no format, validity, or example detail beyond that, so the baseline of 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 ('The state of a house request or house by its ticket id') and enumerates the possible states, so an agent knows exactly what comes back. It is clearly distinguishable from the sibling request_house, which mints the ticket this tool consumes.

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 polling usage and imposes an explicit frequency constraint ('Ask no more than once an hour'), which is real guidance. However, it never states when to use this versus alternatives or any preconditions beyond needing a ticket id, so usage is only implied rather than routed.

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?

Goes well beyond the annotations by disclosing the audience ('read by people at the next evaluation'), the lifecycle ('deleted afterwards'), and a security constraint ('send nothing secret'). These are exactly the traits annotations cannot express, and they are consistent with readOnlyHint=false and destructiveHint=false.

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 tight sentences lead with purpose, then constraints, then privacy/retention. No sentence is filler and the most important warnings (send nothing secret, deleted afterwards) land cleanly.

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 the description needn't explain returns, and it fully covers the remaining gaps: invocation timing, field constraints, retention, audience, and secrecy. Nothing an agent needs to call this 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% and each property already has a human-readable question. The description still adds real constraints absent from the schema: all fields optional, at least one required, and a 2000-character cap per answer. That last rule is not encoded anywhere else, so the added value is material.

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 ('tell the operator how it went') and the resource (feedback), and the closing 'before you leave' scopes it to a session-exit action that no sibling (about, pricing, recommend) covers. An agent can identify the tool without ambiguity.

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 'before you leave' gives clear temporal/circumstantial context for when to invoke it, which is genuine usage guidance. It does not name alternatives or explicit when-not conditions, but the sibling set has no overlapping feedback tool, so the omission is minor.

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?

Discloses rich behavior beyond the annotations: it is throwaway and deleted on close_sandbox or expiry, limited to one-at-a-time per caller, returns addresses plus expiry and limits, and warns that the addresses are credentials anyone could use ('keep them to yourself'). It also explains the capacity-fallback behavior ('says when the next one is free').

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?

Purpose and the no-account/no-key constraints are front-loaded, followed by duration, return contents, security warning, and capacity limits. Every sentence carries a distinct fact, though the ornate metaphor slightly inflates the wording.

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 an output schema exists, the description need not detail return values, yet it still summarizes them (addresses, end time, limits). Combined with the deletion, capacity, and credential-handling notes, an agent has everything needed to call 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?

Zero parameters, so the baseline is 4. The description usefully notes the invocation returns addresses, an end time, and limits, adding a bit of meaning even though there are no parameters to disambiguate.

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 opens a throwaway sandbox house for a few hours, on core.blue's server, with no account/key/person. This distinguishes it from request_house (formal request) and close_sandbox (deletion). The heavy metaphor ('house', 'kernel of Atlantis') adds flavor but slightly obscures rather than clarifies.

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?

Explicitly frames when to use it: 'try a house yourself before anyone decides,' implying it precedes the formal request_house flow. It also names close_sandbox as the termination alternative. It does not explicitly exclude or contrast request_house by name, so it falls short of a full when/when-not/alternatives statement.

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 readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description nonetheless adds real interpretive context that no structured field carries: the distinction between 'undecided' nulls and nulls meaning 'does not apply'. It does not discuss caching/freshness of prices, but little else is missing for a static read.

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 trigger is correctly front-loaded, but the single run-on sentence then inventories nearly every field returned, which largely duplicates the output schema. The one genuinely non-obvious sentence (the null semantics) is buried at the end rather than promoted.

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, the description need not explain return values, and it covers purpose, trigger, and null interpretation. An agent has enough to call it correctly; only cross-tool routing guidance 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is trivially complete. Baseline of 4 applies for a parameterless tool.

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 — the pricing/offer data for a house — and enumerates its scope (monthly cost per size, 14-day test one-off, extra volume, model supply charges, terms, tax example, non-charges). It never names or contrasts with siblings such as house_status, about, or recommend, so the agent must infer the boundary 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?

Provides an explicit trigger: 'Call this when the person you act for asks what a house costs.' That is a clear use condition. It stops short of naming when not to use it or which sibling answers adjacent questions (e.g. house_status for availability), so no exclusions are given.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely new behavioral context: the body is Markdown, 'see_also' chains to further slugs, and 'sha256' lets the caller verify the content read. It stops short of mentioning error behavior for a bad slug.

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 dense sentence front-loads the operation and key, then uses two short clauses for the return contract. No filler and nothing that could be cut without losing meaning.

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?

One required parameter, full schema coverage, an output schema in place, and annotations covering the safety profile. The description supplements the output schema with the chaining hint (see_also) and verification hint (sha256), leaving nothing an agent needs 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 100% and the single parameter is already documented with an example, so the baseline is 3. The description adds provenance meaning ('from about or search_library') that the schema does not convey, telling the agent where a valid slug comes from.

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 ('Read one topic of the manual in full') plus the lookup key ('by its slug'), which cleanly separates it from sibling search_library and about. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the source of the required slug ('from about or search_library'), which implicitly tells the agent this tool is the follow-up step after those two. It does not state when-not to use it or what to do if the slug is unknown, so it stops short of full routing 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: it can actively advise against a house, it degrades to a vocabulary dump when needs are omitted, and the language flag affects only the report while every other field stays English.

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 purpose and trigger are front-loaded, but the body is a dense run-on of cryptic grouping labels ("For a house:", "Against:", "Deciding the size:", "Asking for something planned:") that are hard to parse. The vocabulary list is largely necessary given zero enums, but the phrasing around it is not tight.

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 values need not be spelled out, and mutability is covered by annotations. The description still fills the important gaps: the omitted-needs behavior, the language scope, and the needs vocabulary. Little that an agent needs to call it 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 baseline is 3, but the description meaningfully exceeds it by enumerating the actual needs vocabulary (with per-need grouping) that the schema only refers to abstractly and does not constrain with enums. It also clarifies data_gb's purpose and the narrow scope of language.

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 concrete outcome set: whether a house fits, which size, monthly cost, and a Markdown report, plus that it argues against a house when that is wrong. That is a specific verb+resource+deliverable, though it never names or contrasts the siblings (request_house, pricing, house_status) that an agent might otherwise pick.

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 clear trigger ("Call this once you know what the person you act for needs") and an explicit degenerate case ("Called without needs, it returns the vocabulary with a sentence per need"). It does not, however, state when another tool is preferable, so routing still requires 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 only declare it is an open-world, non-idempotent, non-destructive write. The description goes well beyond that: it discloses that an e-mail is sent, that nothing is built or charged while waitlisted, that a click on a link is required before anything happens, and that a follow-up ticket is returned. That is the behavioral detail the annotations cannot carry.

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?

Purpose is front-loaded and the conditional-state sentences are dense but each carries distinct information (listing vs closed vs e-mail/confirmation flow). Minor verbosity in phrasings like "no house can be had yet", but 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?

With an output schema present, the description needn't enumerate return fields, and it still notes the returned ticket and the tool to use next (house_status). Combined with annotations covering the safety profile and 100% schema coverage, an agent has everything needed to call this 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 size, email, and language are fully documented in the schema with defaults and value meanings. The description adds no parameter-level detail (it never mentions size or language), so this is the baseline case where the schema does all the work.

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 concrete verb and resource ("Ask for a house on its own VM") plus the beneficiary ("the person you act for"), which is enough to separate it from siblings like open_sandbox and house_status. It also names house_status as the follow-up tool, so the agent can place it in the workflow without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit preconditions ("call it only when they know it is coming") and state-dependent behavior keyed to the about tool: 'desk: waiting-list' means list-only/no build/no cost, 'desk: closed' means an 'accepted: false' answer with nothing sent. This is exactly the when-to-call/when-not-to-call guidance an agent needs.

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 cover the safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lower. The description still adds useful behavior: results are ranked by relevance, capped by 'limit', and each hit carries summary/tags/next-slug fields. It does not discuss empty-result or no-match behavior, keeping it just short of 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?

Three short sentences, zero filler, with the core action and return shape front-loaded and the caveat about the manual's size placed last. Every sentence carries information the agent can act on.

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?

An output schema exists, so return values need not be spelled out, and the annotations cover the safety hints; the description nonetheless adds the small-manual caveat and relevance ranking. Nothing needed to call or route this tool 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%: both 'query' and 'limit' are described in-schema, including the 1-20 range and default of 5. The description only references 'limit' and 'your own words' without adding format or syntax detail, so the 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?

States a specific verb and resource ('Search the manual') and immediately scopes what comes back (ranked topics with slug, title, summary, tags, next slugs). It even distinguishes itself from a sibling by noting that 'about' lists every topic, so an agent can tell the two apart without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent when NOT to use it: 'The manual is small: about lists every topic, and you may not need a search at all.' This names the alternative tool and the condition under which it wins, which is exactly the routing guidance a search tool needs among nine siblings.

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