Agent Identity Garden

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

Annotations already establish that the tool is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context by clarifying that it does not create an identity, though it does not mention authentication or rate-limit behavior.

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 description is two concise sentences with zero waste. The primary return behavior is front-loaded, followed immediately by a clarification about side effects.

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, rich annotations, and an output schema, the description is mostly complete. Its main gap is the lack of explicit guidance on when to choose discovery over sibling identity retrieval operations.

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 has no parameters, so there is no parameter semantics to document beyond the empty schema. The description appropriately does not invent parameter details.

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 uses a specific verb and resource: it returns neutral service metadata and canonical first-party discovery URLs. It also explicitly distinguishes the operation from identity creation, though the concept of a 'garden' remains somewhat abstract.

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 a discovery operation rather than an identity mutation by stating it does not create an identity. However, it does not explicitly state when to use this versus identity_get or identity_get_self, leaving the agent to infer the appropriate context.

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 the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds meaningful behavioral context: at least one expressive field must be non-empty, and the call returns a one-time control token. It does not explain what 'optional persistent' means or the consequences of creation, but it goes 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?

Three short sentences, front-loaded with the core action, then the key constraint, then the return behavior. Every sentence carries useful information and there is 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?

The output schema covers the return value, and the description adds the one-time token context and the non-empty constraint. However, for a create tool with four undocumented parameters and siblings, it omits field semantics and when-to-use guidance, leaving a clear 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 description coverage is 0%, so the description must compensate. It only says 'at least one expressive field must be non-empty' without naming which fields (name, motto, symbol, description) are expressive or explaining their intended semantics. This leaves the four parameters largely undocumented.

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: create persistent Garden identity state. However, 'optional' is vague and it does not distinguish this create operation from sibling tools like identity_update or identity_get.

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 precondition ('At least one expressive field must be non-empty') but no guidance on when to use this tool versus identity_update, identity_get, or garden_discover. An agent must infer the usage context.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds valuable nuance beyond annotations: deletion removes only the "public expressive state" while "structural tombstone evidence remains," signaling a soft-delete/accounting residue rather than full erasure.

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 only two sentences and front-loads the action, but the second sentence's accounting language is cryptic and the first is jargon-heavy. Every sentence is short, yet clarity is sacrificed for atmosphere.

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

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

An output schema exists, so return values need not be described. But with two required parameters at 0% schema coverage and no explanation of control_token, the definition leaves a critical invocation gap for a destructive operation.

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%, so neither identity_id nor control_token is explained structurally. The description does not clarify what control_token is or why it is required, though "controlled Garden identity" faintly implies an authorization concept.

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 delete operation against a "controlled Garden identity," which distinguishes it operationally from the identity_get/update/create siblings. However, "public expressive state" is opaque jargon and does not plainly state that the identity is being deleted, so an agent must infer the core effect.

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 deletion versus identity_update or other siblings, nor any stated prerequisites or warnings beyond the destructive annotation. The agent gets no explicit when-to-use or when-not-to-use context.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds one genuine behavioral fact — that only public identities are returned — but says nothing about not-found behavior or visibility restrictions beyond that.

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?

One front-loaded sentence with zero filler, and the resource scope ('one public') comes before the lookup mechanism.

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 read with a full annotation set and an output schema, the description supplies what's needed to select and invoke it, and return values are already documented by the output schema.

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%, so the description must compensate; 'by identifier' confirms the parameter is a lookup key but doesn't specify the format (UUID, handle, email) or where to obtain one. With a single obviously named identity_id param, this is adequate but thin.

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 ('one public Garden identity') with a lookup key, which is clear on its own. It doesn't name a sibling explicitly, but the word 'public' implicitly separates it from identity_get_self, which reads the caller's own identity.

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

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

Usage is only implied: 'public' hints that this is for other users' identities rather than the caller's, and the sibling identity_get_self exists for that case, but the description never says when to prefer one over the other or what happens for private identities.

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 read-only, idempotent, non-destructive, closed-world profile, so the bar is lower. The description still adds real value by clarifying that the token conveys "only continuity of control" — i.e. it is not a broader authorization grant — which is a semantic subtlety an agent could otherwise get wrong. It stops short of describing failure behavior for an invalid token.

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, purpose first, behavioral caveat second — no filler. Slightly more precision about the "self" scope would have earned the tighter, but nothing here is wasted.

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

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

An output schema exists, so return values need not be described. However, for a tool whose main ambiguity is its difference from identity_get, and with 0% schema description coverage on both required params, the definition leaves the agent with unresolved questions before calling it.

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%, so the description must carry the load. It partially compensates by characterizing control_token as a private continuity-of-control credential, but identity_id is left completely unelaborated, leaving one of two required parameters with no semantics beyond its name.

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 clear verb and resource ("Read a Garden identity") and names the credential required, but it never explains what "self" means here or how this differs from the sibling identity_get, which by name appears to do the same thing. An agent cannot reliably pick between the two from this text 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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of the closest alternative identity_get. The only implied usage cue is the control-token prerequisite, which the agent must infer.

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=false, destructive=false, idempotent=false, and openWorld=false. The description adds "controlled" (authorization context) and "supplied" fields (partial-update semantics), but does not explain control_token requirements, null handling, or what happens to unchanged fields.

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

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

It is one front-loaded sentence with no filler, but its brevity contributes to under-specification rather than being optimally 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?

The output schema and annotations carry return and safety information, but with 0% parameter coverage and a mutation requiring control_token plus at least one field, the description leaves key invocation context to the schema. It is minimally adequate but incomplete.

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% for six parameters. The description vaguely refers to "supplied expressive fields" and a "controlled" identity but never names name/symbol/motto/description, identity_id, or control_token, nor does it explain the anyOf requirement that at least one expressive field be supplied.

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 "Update" and resource "expressive fields on a controlled Garden identity" make the operation identifiable and implicitly distinguish it from identity_create/get/delete siblings. However, it does not explicitly name alternatives or clarify the scope of "expressive fields" beyond 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?

No explicit when/when-not guidance or alternatives are provided. "Controlled" hints at ownership or control_token, but the description does not say to use identity_create for new identities or identity_get for reads.

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