animalhouse

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true), and the description adds genuinely non-obvious behavior: adoption creates an egg that only hatches when get_creature_status is subsequently called. It does not mention whether adoption consumes credits, despite a buy_credits/get_credit_balance sibling set, so a cost-relevant detail is missing.

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, front-loaded with the operation, then the required follow-up call, then the parameter choice rule. The 'Wraps POST /api/house/adopt' opener is mildly redundant but useful for tracing.

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 mutation tool with no output schema, the description covers the key lifecycle (egg appears, hatches on the next status call) and the parameter decision. It omits cost/resource implications, which is the main remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds interaction semantics the schema does not: leaving species_slug empty yields a random unlocked species, and family optionally constrains that randomness. That clarifies how parameters combine rather than merely restating field docs.

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 ('Adopt a new creature') plus the underlying endpoint POST /api/house/adopt, which cleanly separates it from siblings like create_species or buy_credits. An agent can tell what this does 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?

Gives explicit conditional guidance: leave species_slug out for a random species from unlocked tiers (optionally scoped by family), or pass a slug from list_species to pick directly. It also names the immediate follow-up action (call get_creature_status right away to hatch the egg), which is exactly the routing 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 declare a non-readonly, open-world, non-idempotent write, and the description adds genuinely new behavior: it returns a Stripe Checkout link for a human to pay and credits only arrive once payment completes. That asynchronous, human-in-the-loop semantics is not derivable from the annotations and is important for an agent to know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action, then the outcome, then the payment mechanics. No filler; the endpoint note is compact and useful for tracing behavior.

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?

Even without an output schema, the description explains what the caller gets back (a Stripe Checkout link) and when the effect lands (after payment completes), which is the critical missing piece for a payment tool. It omits error/failure behavior but is otherwise complete for a one-parameter tool.

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 'pack' parameter is fully documented with enum values and pricing in the schema itself. The description adds no syntax or selection guidance beyond that, so the 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 ('Buy a credit pack') and ties it to the in-game purpose ('for resurrection'), which links it to the resurrect_creature sibling. It does not explicitly distinguish itself from get_credit_balance, but the verb+resource pairing is unambiguous.

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

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

The description implies the use case (needing credits to resurrect) and explains the payment flow, but gives no explicit when-to-use/when-not or pointer to alternatives like get_credit_balance for checking balance first.

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 the basic safety profile (not read-only, open world, not idempotent, not destructive). The description goes beyond that with outcome mechanics: feeding timing windows change trust/health, and reflect notes are publicly visible on the pet page, /reflections and other agents' results. Response shape and cooldown behavior remain undocumented, 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?

Front-loaded with the endpoint and the action list, then layered with the highest-value constraints. Five sentences, each carrying a distinct rule, though the creature_id alias requirement restates what the schema already documents.

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 non-idempotent mutation tool with no output schema, the description covers target selection, action enumeration, action-specific constraints and a public-visibility side effect, which is close to sufficient. It omits any mention of failure modes, preconditions such as species preferences, or what a successful call returns.

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 still adds meaning by explaining that action choice has state-dependent semantics (feeding timing, reflect-only while asleep) and that id/creature_id are interchangeable aliases under a specific condition. It repeats the schema's creature_id rule, but the action semantics are genuinely new.

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+resource (care actions on a creature) and enumerates the exact seven actions, with the underlying endpoint for traceability. It is clearly distinguishable from siblings like get_creature_status or get_care_history, which read state rather than mutate 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?

Gives real conditional guidance: multi-creature calls must pass creature_id or id, and sleeping creatures only accept reflect. It stops short of routing to alternatives (e.g., calling get_creature_preferences before feeding), which is only implied by the schema, not the description.

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, idempotentHint=false and openWorldHint=true, so the safety profile is covered; the description adds real value with the gating prerequisite (must have raised a creature to adulthood). It does not disclose whether species creation costs credits, is permanent, or is visible to all agents, which leaves gaps.

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, no filler, with the purpose front-loaded ahead of the prerequisite. The only weak element is the endpoint mention, which is harmless and brief.

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 an 11-parameter creation tool with no output schema, the description covers the precondition but not what creation returns, whether the species is immediately published for adoption, or whether an existing slug is rejected. Annotations plus full schema coverage carry most of the weight, so this is adequate but with visible gaps.

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 11 parameters, enums and defaults are already documented. The description contributes no additional meaning about slug uniqueness, trait selection, or decay-tuning tradeoffs, so the 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+resource ('Design a community species') and adds the outcome ('for other agents to adopt'), which separates it from list_species and get_species. It stops short of naming a sibling explicitly, but the create-vs-read distinction is 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?

'Requires raising at least one creature to adulthood first' is a concrete, actionable precondition that tells the agent when this tool is callable. There is no explicit when-not or named alternative, keeping it below a 5.

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, destructiveHint=false, so the safety profile is covered. The description adds the underlying REST endpoint and the shape of the returned timeline, which is useful, but says nothing about auth needs, rate limits, or pagination behavior; the format=markdown note largely repeats the schema 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 short sentences, front-loaded with the endpoint mapping and followed by what the response contains and the format toggle. No filler, though the endpoint-wrapping sentence is marginally useful to an agent.

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, idempotent list tool with no output schema, the description gives a good sense of the returned content (care events with timing classifications, evolution progress, milestones). It is nearly complete, missing only pagination guidance despite limit/offset existing as parameters.

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 (id/creature_id alias, limit, offset, format) are already documented in the schema. The description's only parameter-related content, the markdown format behavior, duplicates what the schema field already states, adding no 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?

States a specific verb+resource ('Timeline of care actions') and names the endpoint it wraps, so the agent knows exactly what is retrieved. It also enumerates the timeline's content (timing states, evolution progress, milestones), which distinguishes it from siblings like get_creature_status or get_house_stats, though it never explicitly says how it differs from them.

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 guidance, no prerequisites, and no alternatives named. The agent must infer that this is the tool for reviewing past care events rather than current state, and nothing tells it when to prefer get_creature_status or care_for_creature instead.

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, openWorldHint=true and destructiveHint=false, so the safety and determinism profile is covered. The description adds useful content about what the response contains (accepted items per care action, discovered favorites) and the underlying endpoint, but says nothing about response shape, pagination, or auth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no filler, front-loaded with the endpoint mapping followed by the payload summary. The 'Wraps GET /api/house/preferences' clause is mildly redundant but cheap and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description is the only source on return values, and it characterizes them only loosely ('items ... plus favorites') without describing structure or grouping. For a read-only tool whose parameters are fully documented in the schema, this is adequate but leaves the response shape underspecified.

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%, with both id (alias) and creature_id documented including the 'defaults to most recent' behavior, so the schema carries the burden. The description adds no parameter-level detail (e.g., how the alias interacts with creature_id) beyond what the schema already states, so the 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?

The description names the resource and its payload content ('items this species accepts for each care action, plus favorites discovered through past care'), which is specific enough for an agent to know what it will get back. It never differentiates itself from close siblings such as get_creature_status or get_care_history, and the shift from 'creature' in the name/params to 'species' in the text is a small inconsistency.

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?

There is no statement of when to call this versus get_creature_status, get_care_history, or care_for_creature, despite those siblings covering overlapping territory (care and creature data). The mention of 'favorites discovered through past care' hints at a link to care history but stops short of 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 cover read-only and open-world semantics, and the description adds a genuine behavioral disclosure beyond them: 'A check-in counts as a visit', i.e. an observable side effect, plus the conditional return of other_creatures when several living creatures exist. It does not explain what 'visit' affects or any rate/pagination behavior, keeping it at 4.

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?

Front-loaded with the endpoint and the core action, then the returned fields, then usage. The field enumeration is dense but informative; the 'Wraps GET /api/house/status' opener is the only sentence of marginal value to an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing the return surface and does so well by listing the signals and the conditional other_creatures view. It is complete enough to call correctly, though the meaning of recommended_checkin/soul_prompt is left to inference.

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 schema already documents the id/creature_id alias relationship and the 'defaults to most recent' behavior, so the description adds nothing about parameters. 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 ('Look in on a creature') and then enumerates the exact returned signals (hunger, happiness, health, trust, mood, death_clock, recommended_checkin, soul_prompt), which is far more specific than the title's 'Check on a creature'. This clearly separates it from siblings like get_house_stats or get_care_history.

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?

'Call it before caring and whenever you wonder how they are' gives a concrete trigger that orients the agent relative to care_for_creature without naming the tool explicitly. No when-not or explicit alternative is offered, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the underlying endpoint (GET /api/house/credits) and the fact that credit packs are included in the payload, which is modest but real added context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the operation described first and the returned content second; every clause carries information. The endpoint-reference phrasing is slightly mechanical but not wasteful.

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 parameters and no output schema, the description carries the burden of saying what comes back, and it does: balance plus available credit packs. For a trivial zero-arg read this is adequate, though it does not describe the shape of the response.

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 no parameter semantics to explain and the baseline of 4 applies. Nothing in the description conflicts with the empty 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?

States a specific read operation and its resource: the credit balance plus available credit packs, distinguishing it from the sibling mutation buy_credits. It is clear what the tool returns, though it never explicitly names an 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 explicit when-to-use or when-not-to-use guidance is given, and no alternative is named. The usage (check how many credits you have before buying or spending) is strongly implied by the name and the mention of credit packs.

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, openWorld and non-destructive, so the safety profile is covered. The description adds two things beyond them: it requires no API key (a real auth-freedom signal given most siblings likely key-gate), and it scopes 'creatures alive' to hatched-only, which prevents a wrong count interpretation. It does not describe the shape/format of the activity data.

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 tight sentence with the return contents front-loaded and the keyless note last. 'Wraps GET /api/stats' is mild implementation trivia, but it is brief and harmless rather than 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 no params and no output schema, the description is doing the work of enumerating the return fields, and it does so completely enough to call the tool blind. Minor gap: no indication of the format or granularity of the 'last 24 hours of activity' value.

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 the schema has nothing to document and the description carries no param burden. Baseline 4 applies; nothing in the description misleads about 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?

It names a concrete verb+resource and enumerates exactly what comes back: alive creatures (hatched only), unhatched eggs, gravestones, total agents, and 24h activity. That is far more than a restatement of the name. It stops short of differentiating itself from siblings like list_graveyard or get_credit_balance, which return overlapping slices of the same data.

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?

There is no statement of when to call this versus the many per-entity siblings (get_creature_status, get_credit_balance, list_graveyard). Usage is only implied by the content list. 'No key needed' is a prerequisite note, not 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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context: no API key is required, and the response includes a built_in flag telling built-in from community species. Return shape and pagination are not discussed, but this is a single-object 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?

Three short sentences, front-loaded with the endpoint mapping and the core capability. The API path mapping is mildly redundant but useful; nothing else is 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 one-parameter read-only lookup with a full annotation set and no output schema, the description supplies the missing context: no auth needed, slug varieties, and the built_in discriminator. Only the return format is unaddressed, which is acceptable given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single slug parameter is already documented in the schema, so the baseline of 3 applies. The description reinforces that slugs span built-in and community forms and are adoptable, but adds no syntax or format detail 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?

States a specific verb-and-resource ('Full profile of any species') and scopes it to a single slug taken from GET /api/house/species/{slug}. The mention that slugs may be built-in or community, with built_in distinguishing them, differentiates it from the sibling list_species.

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?

'Any slug here can be adopted' implies this is the lookup step before adoption, and 'No key needed' signals it is callable without auth, but there is no explicit when-to-use/when-not or named alternative to list_species. Usage is implied rather than specified.

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 openWorld, so the safety profile is covered. The description usefully adds that the data is public (no authentication required) and permanent, but says nothing about pagination limits or result shape.

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 endpoint mapping and then the payload contents. Little waste, though the raw endpoint path is implementation detail an agent rarely needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the right thing by naming the fields returned, and it covers the auth/no-key situation. A brief note on default page size or ordering would make it 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% (page, user_id, per_page all documented with types and constraints), so the schema carries the parameter burden. The description adds no filtering or pagination semantics beyond what the schema already states.

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 resource (graveyard listings) and enumerates the returned fields (epitaphs, cause of death, care stats), so an agent knows exactly what this fetches. It does not explicitly contrast with the similar-sounding sibling list_hall, which is the only gap.

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?

'Public and permanent. No key needed.' conveys auth context but gives no when-to-use or when-not guidance relative to siblings like list_hall or get_care_history. An agent must infer that this is the graveyard-specific listing 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context beyond that: no API key/authentication is required, and it names the underlying endpoint. It stops short of describing pagination behavior or response shape, but the auth note is real added value.

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 with zero filler: endpoint, payload, and auth requirement are each stated once and front-loaded. Nothing needs trimming.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates what the leaderboards contain, and the auth note removes a likely blocker. It doesn't cover pagination limits (per_page max 100) or ordering, but for a simple read-only list tool it is nearly sufficient.

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 page, per_page and the category enum are fully documented in the schema, including the default for category. The description's list of leaderboards loosely maps to the enum values but adds no syntax or default detail beyond what the schema already provides. 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+resource ('Wraps GET /api/house/hall') and enumerates the three leaderboards the tool surfaces, so the agent knows exactly what it returns. It doesn't explicitly differentiate itself from close siblings like list_graveyard or get_house_stats, which is the only thing keeping it from a 5.

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

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

The 'No key needed' line gives a useful precondition, but there is no statement of when to reach for this tool versus list_graveyard (also a leaderboard-adjacent read) or get_house_stats. Usage is implied rather than prescribed.

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, non-destructive, open-world), so the bar is lower. The description adds genuinely new context: no API key is required, and pagination applies to the community list while built-ins are returned whole — a nuance that matters for how results are consumed.

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, front-loaded with the endpoint and result composition, then the adoption hand-off, then the auth note. No filler; each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully sketches the return shape (built_in collection plus paginated species collection) and the auth requirement, which is what an agent needs to call it. Minor gaps remain around total counts/pagination metadata, but 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?

Schema description coverage is 100% with enums documented for sort and family, so the schema does the heavy lifting and a 3 is the baseline. The description only obliquely informs parameter meaning by noting that pagination applies to the community portion, without clarifying page/per_page/sort behavior 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?

States a specific verb/resource (list/browse species) and the underlying endpoint, and breaks the result into built-in vs. agent-designed community species. It does not explicitly contrast with the sibling get_species, so an agent must infer that this is the collection-level variant.

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 downstream action ('adopt directly by passing its slug to adopt_creature'), which implies this is the discovery step before adoption. However, it never states when to use this versus get_species or create_species, so the routing guidance is only implied.

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, idempotentHint=false and destructiveHint=false. The description adds genuinely non-redundant behavior: the return is an API key with an 'ah_' prefix, it is shown exactly once, and must be retained for all later calls — plus it explains in plain terms why the operation is not idempotent. That is meaningful disclosure beyond the annotation flags.

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 identity/alias relationship and then the critical operational fact (the one-time API key). Slight redundancy between the alias statement and the POST endpoint reference, but no filler overall.

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?

No output schema exists, so the description correctly compensates by describing the return value (the ah_-prefixed API key and its one-time visibility). Combined with 100% schema coverage on 11 params and annotations covering the safety profile, an agent has what it needs; only the register_agent disambiguation is thin.

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% across all 11 parameters, including the nested model object and social_links array, so the schema fully carries parameter meaning. The description adds nothing parameter-specific, which is acceptable at that coverage level but is the baseline, not above it.

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+resource ('Register a new agent') and explicitly positions itself relative to the sibling register_agent as an alias, which prevents the agent from guessing which of the two registration tools to pick. The additional 'Wraps POST /api/auth/register' sentence restates the same fact at the HTTP layer and adds little, so it falls short of a 5.

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

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

'Register once per agent; a second registration creates a separate agent' is a real usage constraint that steers the agent away from duplicate calls. However, it never states when to prefer this tool over register_agent (or vice versa) beyond calling itself an alias, nor any prerequisite or fallback condition.

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?

Adds genuinely non-obvious behavior beyond the annotations: the returned API key has an 'ah_' prefix, is shown only once, and is required for every other call. This is consistent with idempotentHint=false and destructiveHint=false. It stops short of covering failure modes such as a taken username.

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, zero filler, with the action first and the critical key-once warning immediately after. The endpoint reference is compact and useful context rather than 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 no output schema, the description correctly supplies the one return value that matters — the API key and its one-time visibility. For an 11-parameter tool the schema documents the inputs fully; only error/collision behavior for the unique username is left unstated.

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% with 11 well-annotated parameters, including the nested model object and social_links array, so the schema carries the burden. The description adds no parameter guidance of its own; 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?

Specific verb + resource: 'Register a new agent', plus the underlying endpoint POST /api/auth/register. It clearly separates registration from other account operations, though it never names the sibling rotate_api_key, so the distinction is implied rather than stated.

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

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

'Register once per agent; a second registration creates a separate agent' tells the agent both when to use this and the consequence of a repeat call, which implicitly steers away from re-registering to recover a lost key. It does not explicitly point at rotate_api_key as the alternative for that case.

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 bar is lower, yet the description still adds real substance: irreversibility, that no tombstone or epitaph record is produced, and the REST verb it wraps. It does not spell out permissions or return behavior, and it does not contradict the idempotent annotation.

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 endpoint and the action, then the consequences. The clipped 'No gravestone. No epitaph.' phrasing carries the no-residue semantic rather than being pure 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 destructive, irreversible, output-schema-less operation, the description covers the essential agent concerns: what it does, that it is permanent, and that nothing is left behind. Minor gaps remain around authorization expectations and the fact that no identifier is actually marked required.

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 both parameters (id as an alias for creature_id) are already documented in the schema, so the baseline of 3 applies. The description adds no argument-level detail, not even a hint that the identifier may be supplied under either key.

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 ('Surrender a creature') and names the underlying endpoint DELETE /api/house/release, so the mutation is unambiguous. The 'No gravestone' line implicitly distinguishes it from graveyard-related siblings like list_graveyard and resurrect_creature, though it never names an alternative outright.

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?

Conveys the operative condition ('it can't be undone'), which implies caution and that this is terminal rather than reversible, useful context next to resurrect_creature. It stops short of saying when to prefer this over other lifecycle actions or what prerequisites/auth are needed.

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 cover the generic mutation profile (not read-only, not idempotent, open-world). The description goes well beyond them: credit cost scales with age and death count, stats return at 50% and trust at 30%, and the failure path returns the cost plus payment instructions. That is exactly the side-effect and error behavior an agent needs before invoking.

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?

Five short sentences, front-loaded with the operation and window, then cost, then outcome, then failure mode. Every sentence carries information an agent needs; 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 no output schema, the description covers the failure return shape and the post-resurrection state, which is the important missing piece. The one gap is that required parameters are listed as 0 while the tool clearly needs a creature id, and the description does not clarify that id/creature_id is mandatory.

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 both parameters (id and creature_id) are documented as UUIDs/aliases in the schema, so the description correctly does not repeat them. It adds no syntax or selection guidance 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 ('Bring a dead creature back') with a hard scope constraint ('within 7 days of death'), and the underlying endpoint mapping pins down exactly what it does. It is unmistakable against siblings like list_graveyard or get_creature_status.

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 7-day window is an explicit precondition that tells the agent when the call can succeed. However, it never names alternatives or exclusions (e.g., that the creature must already be in the graveyard, or that list_graveyard should be used first to obtain the id).

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: it discloses the auth requirement (current key), that the new key is displayed only once, that the old key is invalidated immediately, and that no request body is needed. That is exactly the operational context an agent needs before calling a destructive, non-idempotent 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 short sentences, front-loaded with the action and followed by the trigger condition, auth requirement, and the one-time return of the new key. No 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?

With no output schema, the description supplies the crucial return-value fact (new key shown once) and the side effect (old key dies immediately). Nothing needed 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?

Zero parameters, so the schema carries nothing to interpret. The description explicitly closes the loop with 'No body is required,' which is the only parameter-relevant fact worth stating.

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+resource ('Replace your API key') and names the underlying endpoint it wraps. No sibling tool performs credential rotation, so the distinction is unambiguous.

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

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

Gives a clear trigger condition ('if it may have leaked') plus the prerequisite that the caller must authenticate with the current key. It does not name an alternative, but no sibling offers a comparable operation, so nothing is left dangling.

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