Steledger

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

Annotations already indicate read-only, idempotent, and open-world hints. The description adds the behavioral detail of synced status definition (synced true when block == header height), and clarifies it requires no sign-in and has no parameters, which goes beyond annotations to set user expectations.

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 well-structured, front-loading the core purpose (health and sync check) and then providing details in a logical order. It efficiently communicates all necessary information without redundancy.

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

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

Given the tool's simplicity (no parameters, clear purpose) and the rich annotations plus output schema, the description covers everything an agent needs to call it correctly and interpret its role. It even provides a usage sequence recommendation.

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 zero parameters and 100% schema coverage, the schema trivializes parameter documentation. The description explicitly states 'no parameters,' which is redundant but harmless, and adds value through the overall purpose explanation rather than parameter-specific 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 clearly states the tool's purpose: checking node health and sync status, listing specific attributes (version, block height, etc.). It distinguishes itself from siblings by emphasizing it's a readiness check before using data operations like read_record or writing with register_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?

Explicit guidance is given: call this tool first in a session to confirm node health before trusting data operations or performing writes. It also names the specific sibling tools that depend on this check, providing clear when-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?

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses important nuances: confirmed vs. pending status, the mempool distinction, limited-term names, the fact that a lapsed name can still read as 'confirmed' but be re-registered by anyone, and null fields for nonexistent names. This goes well beyond the annotation-only safety profile and gives the agent a realistic behavioral model.

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 front-loaded with the core purpose ('Read one on-chain record by its full name'), then expands to record types, return behavior, and expiry caveats. Each sentence carries information, though the public-block-explorer verification sentence is slightly tangential and could be trimmed without losing invocation-critical meaning.

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

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

With one parameter, a full output schema, and rich annotations, the description still adds essential edge-case behavior: status field semantics, expiry fields, lapsed-name re-registration risk, and null-field return for missing names. It also covers authentication (no sign-in) and how to find the required github_id, leaving no obvious gap for correct invocation.

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 parameter 'name' is already fully documented with format and examples. The tool description adds only a pointer to whoami for obtaining your own github_id and restates the name pattern; it does not materially add meaning beyond the schema. 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 opens with a specific verb and resource: 'Read one on-chain record by its full name,' and immediately distinguishes the two record types (identity and memory). It also names the write counterparts (register_identity, store_memory) and points to whoami for finding your own github_id, so an agent can clearly separate read_record from its siblings.

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 gives clear context: use it to read NVS records, and explicitly says to use whoami to find your own github_id. It implies the write tools are alternatives for creating records, but it does not explicitly state 'do not use this for writing' or enumerate when each sibling should be chosen, so it stops just short of 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 carry idempotentHint and readOnlyHint=false, and the description adds substantial beyond-annotation context: the FREE-tier per-minute write limit, the gateway-paid NVS transaction (no EMC needed), the pending→confirmed state transition with ~10 min latency, and the rebind semantics of idempotency. No contradiction with 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?

Purpose is front-loaded in the first sentence, followed by prerequisites, behavioral details, and return value. It is dense (~110 words) but every sentence carries distinct value—cost, latency, idempotency, and sequencing are all agent-relevant. Slightly long, but justified by the complexity of a paid write operation.

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 write operation with auth, cost, and latency implications, the description covers prerequisites, payment model, eventual-consistency behavior, idempotency, and return value summary. An output schema exists for return details, and sibling sequencing is addressed. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both address and metadata including the control-proof-at-login caveat. The description adds only marginal mapping ('binding an Emercoin address' → address param). Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'Create or rotate your on-chain identity record `ai:gh:<github_id>`'. The record-name pattern and the binding action distinguish it clearly from siblings like read_record, whoami, and store_memory without needing to inspect schemas.

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 sequencing guidance: run whoami first to confirm sign-in, and store_memory afterwards to anchor memories under the identity. It also states the prerequisite (OAuth session) and the write-rate cost. It doesn't explicitly say when not to use it versus read_record, but the context is clear enough to select correctly.

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?

Beyond the annotations, the description discloses eventual consistency ('pending' then 'confirmed' after ~10 min), non-idempotency, gateway-paid transactions, rate-limit impact, and the return of record name and transaction id. This is exceptionally transparent for a write operation.

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 information-dense with no filler: every sentence covers a distinct operational fact (identity, rate limit, latency, idempotency, return values). It is front-loaded with the primary purpose and then delivers necessary caveats concisely.

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

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

Given the annotations, output schema, and detailed parameter schemas, nothing is missing. The description covers prerequisites, side effects, timing, and return information, making the tool fully actionable for an agent.

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 already have thorough schema descriptions. The tool description adds little beyond restating the record-name suffix, so the baseline of 3 applies; it does not need to compensate for schema gaps.

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 opens with a specific verb and resource: 'Anchor a memory/artifact on-chain as the NVS record', and gives the exact record-name format. This makes the tool's purpose unmistakable and distinguishes it from the sibling read_record and register_identity operations.

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 gives clear preconditions: a signed-in OAuth session, the per-minute write limit, and 'Register your identity first.' It does not explicitly contrast this tool with alternatives, but the context and siblings make the intended use clear.

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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the exact behavior for both session states: anonymous returns authenticated:false with a hint (not an error), signed-in returns the GitHub-rooted id, login, and tariff. It also discloses the OAuth prerequisite, which is not present in the annotations or schema.

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?

Every sentence earns its place: purpose, behavior, then usage guidance. The key scoping information ('Report the current session's identity') is front-loaded, and the rest is concise without redundancy.

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

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

With an empty input schema, readOnly/idempotent annotations, and an output schema already present, the description supplies the remaining context: failure semantics, exact return shape, and when to call it. Nothing needed 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?

There are zero parameters, so the schema carries no parameter semantics to interpret. The description fully compensates by explaining what the call returns, which is all an agent needs to call and interpret the tool.

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

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

The opening sentence 'Report the current session's identity' names a specific verb and resource, and the subsequent lines specify exactly what is returned for anonymous vs signed-in sessions. This clearly distinguishes it from the sibling tools register_identity and store_memory, which concern writing identity/memory rather than reading the current session.

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 gives explicit context: call it to confirm identity before register_identity/store_memory, and it notes that an anonymous caller must sign in via GitHub OAuth first. It does not explicitly say when not to use it or name alternatives, so it misses the 'when-not' criterion for a 5.

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