Writing Helpful GraphQL Schema Comments

Upon adding a SubQuery GraphQL Agent to your AI Agent, we will ingest the GraphQL schema from the provided IPFS CID to understand:

• What data is available in your indexer project

• What the data means

• How different entities relate to each-other

• Which questions can we answer based on the indexer project

A properly formatted, logically named, and well commented GraphQL Schema is necessary to get the most out of your AI Agent.

Example GraphQL Schema

"""
Delegator entity represents users who delegate tokens to indexers to earn rewards.
Tracks total delegations across all indexers with era-based value changes.
exitEra is set only when completely exiting (totalDelegations <= 0), otherwise remains -1.
"""
type Delegator @entity {
  """
  Delegator wallet address
  """
  id: ID!
  """
  AI/LLM Warning: Do not use this field for filtering or queries. Use totalDelegationsEra, totalDelegationsEraValue, totalDelegationsEraValueAfter instead
  """
  totalDelegations: EraValue!
  totalDelegationsEra: Int!
  totalDelegationsEraValue: BigInt!
  totalDelegationsEraValueAfter: BigInt!
  delegations: [Delegation] @derivedFrom(field: "delegator")
  claimedRewards: [Reward] @derivedFrom(field: "delegator")
  unclaimedRewards: [UnclaimedReward] @derivedFrom(field: "delegator")
  """
  Era when first started delegating (or re-entered after complete exit)
  """
  startEra: Int!
  """
  Era when completely exited all delegations. -1 means still actively delegating
  """
  exitEra: Int!

  """
  Block number when record was created
  """
  createdBlock: Int
  """
  Latest event details: topicHandler:blockNumber
  """
  lastEvent: String
}

"""
Delegation entity represents a specific delegation relationship between a delegator and an indexer.
Each delegator can have multiple delegations to different indexers.
exitEra is set only when completely exiting this specific delegation, partial withdrawals just update amount.
"""
type Delegation @entity {
  """
  Composite ID: delegator address + indexer address
  """
  id: ID!
  delegator: Delegator!
  indexer: Indexer!
  """
  AI/LLM Warning: Do not use this field for filtering or queries. Use amountEra, amountEraValue, amountEraValueAfter instead
  """
  amount: EraValue!
  amountEra: Int!
  amountEraValue: BigInt!
  amountEraValueAfter: BigInt!
  """
  Era when this specific delegation to the indexer was completely exited. undefined/null means still active
  """
  exitEra: Int

  """
  Block number when record was created
  """
  createdBlock: Int
  """
  Latest event details: topicHandler:blockNumber
  """
  lastEvent: String
}

Principles for Writing Helpful GraphQL Schema Comments

Think like onboarding a new teammate:

• Write comments as if explaining to someone who just joined the project and needs to maintain or extend it.

• Assume they know GraphQL syntax but not your domain or design choices.

• Be concise: Keep explanations short and to the point. Avoid unnecessary verbosity to reduce token usage and make parsing easier for AI.

• Define terminology clearly: If you use domain-specific terms or abbreviations, explain them. This avoids ambiguity for both humans and AI.

• Explain the purpose of each entity: Describe why the entity exists, what real-world or business concept it represents, and how it differs from other related entities.

• If multiple entities look similar, explain why they are separate and when to use each one.

• Field-level documentation: For every field, explain its meaning, expected format, and constraints. For IDs, document the generation/derivation rule (e.g. prefix conventions, hashing strategy, compound keys).

• Describe relationships and usage: If a field links to another type or is part of a broader workflow, note the connection. Mention if the relationship is one-to-one, one-to-many, or derived.

• Indicate business rules and edge cases: If certain fields are only present in specific conditions, or have business logic attached, note it.

• Document evolution intent: If a field or type is temporary, deprecated, or reserved for future extension, make it clear.

• Clarify query performance considerations: Highlight fields that are expensive to resolve, require joins, or should be queried sparingly.

• Consistency in style: Use consistent phrasing, formatting, and tense in comments to reduce noise and make parsing easier for both humans and AI.
  

Updating your SubQuery GraphQL Agent’s Schema

After updating your GraphQL Schema, deploy it to IPFS to obtain a new CID.

Replace the SubQuery GraphQL Agent’s CID to see the changes.

Your AI Agent does not need to be rebuilt after modifying SubQuery GraphQL Agents.