Emer Ai Tools

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by noting no sign-in required, no parameters, and detailing the sync state condition (synced true once block == header height). It also explains the tool's role in establishing node health before other operations. While annotations cover safety, the description adds behavioral and workflow 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?

The description is three sentences long, each serving a distinct purpose: reporting what it does, stating properties (read-only, no sign-in, no params), and providing usage guidance. It is front-loaded with key information and contains 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?

Given that an output schema exists (though not shown), the description appropriately focuses on high-level output fields and the sync condition. It also provides essential workflow context ('call it first'). With rich annotations and an output schema, this description is complete and leaves no gaps.

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

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

There are no parameters, and schema coverage is 100%. The description explicitly states 'no parameters.' Since there is nothing to add beyond the schema, the baseline of 4 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 clearly states it reports the node's version, block height, header height, peer connections, and sync state. It specifies it's read-only with no sign-in or parameters, and explicitly distinguishes from sibling tools by advising to call it first before using read_record, register_identity, or store_memory.

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 explicitly states when to use this tool: 'Call it first in a session to confirm the node is healthy and fully synced before trusting read_record or writing...' This provides clear guidance on usage context and ordering relative to sibling tools.

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, openWorldHint, and idempotentHint. The description adds beyond that: it returns confirmed or pending records from mempool, distinguishes via 'status' field, and returns null fields for non-existent names. 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?

The description is well-structured with main action first, followed by examples, behavior clarifications, and related commands. It is slightly long but every sentence adds value, making it efficient for 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?

Given the simple single-parameter input and presence of output schema, the description explains return states (confirmed/pending), status field, and null behavior for non-existent names. It is complete for agent understanding without needing to inspect 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 100% and the description enriches the single parameter by providing concrete examples of valid name formats (ai:gh:<github_id> and memory variants), explaining their provenance, and clarifying that any existing NVS name works. This adds meaning beyond the schema's description.

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 specifies the verb 'read' and resource 'NVS record' with clear naming patterns for identity and memory records. It distinguishes from siblings like register_identity and store_memory by focusing on reading vs. writing, and from whoami by addressing record types.

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 states when to use the tool (to read a record by full name) and hints at alternatives (whoami for finding own github_id). It notes read-only, no sign-in required, and behavior for non-existent names, but lacks explicit when-not-to-use or direct sibling comparison.

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

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

Adds significant detail beyond annotations: requires OAuth session, counts toward write limit, NVS transaction paid by gateway, pending then confirmed after ~10 min, idempotent. Annotations only hint at idempotency and openness.

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 dense, front-loaded sentences with no filler. Every phrase adds value, covering action, prerequisites, mechanism, idempotency, and return values.

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 prerequisites (OAuth, whoami), behavior (write limit, transaction, latency), idempotency, return values (record name, tx id), and post-conditions (use store_memory). Complete for a 2-param tool with 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 100%, but description adds context: address is 'anchor for later signature login' and metadata is 'stored verbatim'. Also notes return values beyond 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?

Description clearly states the tool creates or rotates an on-chain identity record binding an Emercoin address to a GitHub identity. It distinguishes from siblings by referencing whoami and store_memory for pre- and post-conditions.

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?

Explicitly instructs to run whoami first and use store_memory afterwards, providing clear context. Does not explicitly state when not to use, but the guidance is strong.

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 the tool is not read-only and not idempotent. The description adds details on rate limits, transaction cost, and confirmation delay (~10 min). It provides contextual behavior beyond the annotations without contradicting them.

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 a single paragraph covering all necessary information without redundancy. It is well-organized and front-loaded with the core action, though it could benefit from bullet points for readability.

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 complexity (write operation with external dependencies), the description covers prerequisites, behavior, timing, and limitations comprehensively. The output schema exists, so return values need not be detailed.

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 100% schema coverage baseline at 3, the description adds value by explaining the content_hash becomes the record's suffix and that content stays off-chain. Metadata description matches the schema but still clarifies usage.

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 explicitly states the tool anchors a memory/artifact on-chain as an NVS record with a specific format. It clearly identifies the action (store), resource (memory/artifact), and output format, distinguishing it from sibling tools like read_record or 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?

The description provides clear prerequisites (signed-in session, registered identity), notes rate limits, and idempotency behavior. It does not explicitly mention when not to use or suggest alternatives, but the sibling tools cover complementary actions.

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?

Description adds details beyond annotations: no sign-in required, anonymous returns {authenticated: false} with hint, signed-in returns {authenticated: true} plus id/login/tariff. Annotations already indicate read-only and idempotent, no contradiction.

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 sentences, each valuable: first states purpose, second details behavior, third gives usage context. No wasted words.

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 0 parameters and output schema present, the description covers all needed aspects: behavior, return format, and usage guidance.

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?

No parameters exist, so baseline 4 applies. Description correctly notes the tool takes no arguments, providing no additional parameter semantics needed.

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 'Report the current session's identity' which clearly indicates the tool's purpose. It distinguishes from siblings like register_identity and store_memory by focusing on identity retrieval.

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 provided: 'Call it to confirm who you are before register_identity / store_memory; an anonymous caller must sign in (GitHub OAuth) first.' This tells when to use and what prerequisites exist.

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