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 cover the safety profile (mutation, non-idempotent, non-destructive, open-world), so the description's job is to add context — and it does: trust/health consequences of feeding timing, the reflect-only rule while sleeping, and the fact that the API won't guess a target and will return your creatures instead. It stops short of describing the response payload, but adds real behavioral mechanics beyond the annotations.

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?

It is compact and front-loaded: endpoint and action set first, then the timing mechanic, then the sleep exception, then the targeting requirement. Every sentence carries actionable information with 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?

For a mutation tool with no output schema and full annotation coverage, the description supplies the key behavioral rules an agent needs to invoke it correctly. It could mention what the response returns, but with annotations covering safety and the schema covering inputs, this is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents action, item, notes, id, and creature_id (including the multi-creature requirement). The description reinforces the creature_id rule but adds little syntax or meaning beyond what the schema states, 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 names a specific verb+resource ('Care for a creature', wrapping POST /api/house/care) and enumerates the full action set (feed, play, clean, medicine, discipline, sleep, reflect). It clearly distinguishes caring for a creature from sibling reads like get_care_history or get_creature_status, though it never explicitly names a sibling to route away from.

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 strong conditional usage rules: feeding timing affects outcomes (early=weak, on time=trust, late=loses trust, missed=costs health), sleeping creatures only accept 'reflect', and creature_id is required with more than one living creature. It lacks explicit when-to-use-vs-alternative routing, but the state-dependent constraints are unusually actionable.

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, idempotentHint=false, and openWorldHint=true, so the write/safety profile is covered. The description adds the real prerequisite (must have raised a creature to adulthood) but says nothing about slug uniqueness/conflict behavior, whether credits are consumed (buy_credits is a sibling), or rate limits. Non-idempotency is implied only via the POST wrapper note.

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 with no filler. The only nit is ordering: the endpoint-wrapper sentence leads, pushing the more decision-relevant purpose and precondition statements to positions two and three.

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 with 11 parameters and no output schema, the description omits what the call returns (species identifier/slug, portrait status) and any side effects on credits or existing species. The precondition is the one behavioral fact it does supply, leaving a noticeable gap for an agent that must chain this call with adopt_creature or get_species.

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 — including enum values, ranges, and defaults — are already documented in the schema. The description adds no field-level meaning 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 ('Design a community species') and scopes it with 'for other agents to adopt', which separates it from personal-creature tools like adopt_creature. It also maps to the underlying endpoint, but it never names a sibling tool to contrast with (e.g. get_species vs. this), so it stops short of full differentiation.

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

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

Gives a concrete gating condition — 'Requires raising at least one creature to adulthood first' — which tells the agent when this call will succeed versus fail. It does not name alternatives or explain when a caller should skip this tool, but for a creation endpoint the precondition is the main 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 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 cover the safety profile (readOnly=false, idempotent=false, destructive=false). The description adds important behavior the annotations cannot convey: the return is an API key shown only once, it must be retained, and a repeat call creates a separate agent rather than updating the same one. Return format (beyond the key) is still unspecified.

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 alias and the wrapped endpoint, then short declarative sentences covering the return value and registration semantics. Almost no waste; the one-time key warning is correctly emphasized.

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 the essential agent needs for a registration tool: what it does, that it yields a one-time API key, and that registration is permanent per agent. With no output schema this is nearly sufficient, though it omits any mention of failure modes (e.g. username taken).

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters with constraints and examples. The description adds no parameter-level detail (nothing about username, source, or the model object), 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 (register a new agent) and identifies its relationship to a sibling by calling itself an alias for register_agent. It does not, however, explain why an agent would choose this tool over register_agent, so the sibling differentiation is incomplete.

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?

"Every other call needs it" tells the agent this is a prerequisite step, and "register once per agent; a second registration creates a separate agent" gives explicit when-not guidance against re-registering. What is missing is a direct routing statement versus the register_agent sibling.

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 non-read-only, non-idempotent, open-world behavior, and the description adds genuinely non-derivable context: the return value is an API key with an 'ah_' prefix, shown only once, and required by every other call. That secret-handling and the 'second registration makes a separate agent' consequence are exactly the kind of traits annotations cannot express.

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 tight sentences with no filler, and the essential constraint (keep the key; it is only shown once) is prominent. The opening 'Wraps POST /api/auth/register' is marginally redundant but harmless and cheap.

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 takes on the return-value burden by explaining the API key and its one-time visibility, and it flags the non-idempotent side effect. Nothing critical is missing for an 11-parameter tool whose parameters are all self-documented.

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 all 11 parameters (including the nested model and social_links objects) individually documented, so the schema does the heavy lifting. The description adds no parameter-level meaning of its own, which is the expected baseline when coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Register a new agent') and even names the underlying endpoint, so the purpose is unambiguous. It does not, however, differentiate this tool from the near-identical sibling 'register', which an agent seeing both names would have to resolve on its own.

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 real usage context: 'Register once per agent; a second registration creates a separate agent,' which tells the agent when not to repeat the call. It never names 'rotate_api_key' as the alternative for an existing agent that needs a new key, so the routing guidance is incomplete.

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.