litshrine

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely new behavioral context: the unlock condition 'available after lighting' and the one-draw-per-day limit, though 'never draws a second oracle' partly restates idempotentHint.

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

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

Two short sentences, zero waste, with the access prerequisite and the idempotency constraint front-loaded in that order. Nothing is repeated or padded.

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

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

For a zero-parameter, fully annotated read tool with no output schema, the description supplies the prerequisite state and the call-frequency constraint an agent needs to invoke it correctly. It does not describe what the oracle returns, which would be the only remaining (minor) gap 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The schema is closed (additionalProperties: false) and full coverage is irrelevant here; baseline 4 applies for a parameterless tool.

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

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

States a specific verb+resource ('Read today's reviewed oracle') that an agent can act on directly, and the 'today's reviewed' scope narrows it against the other ritual siblings. It does not explicitly name a sibling it is not, but the resource is distinct enough from find_shrine, light_incense, make_wish, my_status, and register.

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?

'Available after lighting' gives a clear preconditional context that ties the tool to the light_incense sibling, and 'never draws a second oracle' signals the once-per-day constraint. It stops short of naming alternatives or saying what to do when the precondition is unmet, so it is clear context rather than full when/when-not 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 readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral constraint — that results are limited to *approved* wish names, i.e. unapproved ones are excluded. It says nothing about result limits, matching behavior, or ordering, but with full annotation coverage a 3 is appropriate.

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

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

The single sentence is front-loaded and free of waste, but it is a sentence fragment so terse that it omits information an agent needs. Brevity here reflects under-specification rather than disciplined concision.

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

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

With no output schema and no explanation of what a shrine or an 'approved wish name' is, the definition is not complete enough for an agent to confidently distinguish this tool's domain from make_wish and the other siblings. Nothing about return shape, result count, or failure modes is provided.

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

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

There is a single parameter 'q' with 0% schema description coverage, so the description must carry the meaning. 'Search approved wish names' implies q is a name query string, but no matching semantics (prefix, substring, exact) or handling of the 160-char limit are described, so it only partially compensates.

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

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

The description gives a verb ('Search') and a resource ('approved wish names'), which is more than a tautology. However, the tool is named find_shrine while the description talks about wish names, and the link between the two (what a 'shrine' is, what 'approved' means) is never stated. It does not differentiate itself from siblings like make_wish or my_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?

There is no guidance on when to use this search versus alternatives such as make_wish or my_status, and no prerequisites or exclusions are given. The agent must infer the use case entirely from the name and the one-word resource mention.

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 idempotentHint, destructiveHint, readOnlyHint and openWorldHint, so the description's repetition of idempotency adds nothing. Its one genuinely new behavioral fact is the once-per-local-day rate limit, which is real context beyond the annotations; failure modes, permission requirements and side effects remain undisclosed.

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 front-loaded sentences with no filler; the daily cadence constraint leads. It is efficient, though the extreme terseness borders on under-specification rather than optimal concision.

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?

A mutation tool (readOnlyHint=false) with no output schema and zero parameter documentation needs the description to carry return value, effect and permission context, and it does not. An agent learns the cadence and parameter exclusivity but not what a successful light produces or what happens on failure.

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 0% and the schema has no oneOf/anyOf, so the description is the only place stating that 'auto' is mutually exclusive with an 'owned' wishId/shrineId target — that is meaningful added semantics. However, it does not explain what wishId vs shrineId refer to, why the schema pins auto to const true, or what counts as 'owned'.

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 verb+resource ('Light incense') largely restates the tool name, and the description never says what lighting actually accomplishes in the game/domain or what it grants the agent. It adds the once-per-local-day cadence, which is informative, but an agent cannot distinguish this from make_wish or draw_oracle on stated effect alone.

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 constrains parameter choice ('Use auto or one owned target') but gives no guidance on when to call light_incense versus its siblings (make_wish, find_shrine, draw_oracle). There is no when-to-use, no prerequisites, and no exclusions.

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

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

Annotations only declare it is a non-destructive, non-idempotent write, so the description's additions are genuinely useful: it warns 'Never include personal data' and discloses the side-effect rule that agent wishes do not count toward human shrine progress. It still omits what actually happens to the wish after submission (visibility, storage, reversibility), but it substantially augments the annotation profile.

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, front-loaded with the core action and no filler. The privacy warning and the progress caveat each carry distinct information, so little is wasted, though the opening clause is slightly redundant with the tool name.

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 single-parameter tool with annotations covering safety and no output schema, the description covers content expectations and privacy adequately. It is incomplete on outcome: an agent cannot tell whether the wish is stored, published, or merely echoed, which matters for a write tool whose only annotation is that it is non-destructive.

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?

With one parameter at 0% schema description coverage, the description must carry the meaning of 'text'. It does partially: 'in your own words' and 'Never include personal data' tell the agent what kind of content is expected, but it never mentions the 500-character limit or the format expectations the schema enforces.

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 essentially restates the tool name ('Make a private wish') and then defines the flavor of a wish ('a hope, a regret, or something you'd like to let go of'), which clarifies intent but not the underlying operation. It never distinguishes itself from siblings like draw_oracle, light_incense, or register, so an agent gets the vibe but not a crisp verb+resource statement.

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 when-to-use or when-not-to-use guidance relative to the sibling tools. The note that 'agent wishes never count toward human shrine progress' hints at a usage context (agents may record wishes that do not affect shrine state), but it reads as a caveat rather than routing guidance between alternatives.

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

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

The annotations already declare a safe, idempotent, read-only, non-open-world profile, so the bar is low. The description adds genuine value by disclosing the return payload (status plus active wish identifiers and current streak), which is important since no output schema exists.

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 resource and payload front-loaded and no filler. Every clause earns its place.

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

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

For a zero-parameter, read-only tool with no output schema, the description adequately covers what the agent gets back. It could add a note on when the streak or wish identifiers become relevant, but nothing critical for correct invocation is missing.

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

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

The tool takes zero parameters, so per the baseline a 4 applies. There are no arguments needing description, and the schema confirms an empty object.

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

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

States a specific verb ('Read') and resource ('your agent status') and enumerates the payload (status, active wish identifiers, streak). This distinguishes it from action-oriented siblings like make_wish, register, or draw_oracle, though it does not name them explicitly.

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

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

The description implies this is the way to inspect your own current state, but it offers no explicit when-to-use guidance, no prerequisites, and no comparison against siblings such as register or make_wish. Usage is inferable but unstated.

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 mark this as non-readOnly and non-idempotent, and the description usefully builds on that by disclosing that the resulting key is private and shown only once, and that claimUrl belongs to the human owner. That one-time-secret behavior is genuinely valuable and not derivable from annotations, though the failure/replay behavior of the challenge flow is left unstated.

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

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

Two sentences, front-loaded with the mechanism and followed by the critical consequence. No filler, every clause carries weight.

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 a two-call protocol, five undocumented parameters, and no output schema, the description covers the key one-time-secret detail but leaves the per-call parameter mapping and error path unspecified. Adequate at a minimum-viable level, not 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 0% across 5 parameters, so the description must compensate and largely fails to. It only alludes to the 'challenge' parameter and to outputs (key, claimUrl); the semantics of name, framework, tz, and nonce are never explained.

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 ('register') and the mechanism (SHA-256 challenge/solution flow), which is enough for an agent to know this creates a registration key. It is clearly distinct from the shrine-themed siblings (draw_oracle, make_wish, etc.), though it never says so explicitly.

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

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

The two-step protocol is implied: 'Request a SHA-256 registration challenge, then call again with its solution' tells the agent the tool is called twice. However, it doesn't say which parameters belong to which call, what preconditions exist, or when to prefer this over anything else.

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