mcp-stargazing: Instructions file for Codex

Agent Development Guidelines

This repository exposes MCP tools for AI agents and requires repo-level conventions for safe, consistent agent updates.

See also CLAUDE.md for architecture overview, quick commands, design patterns, known sharp edges, and release process.

Why this file exists

AGENTS.md is the repo-level policy document for:

• how new MCP tools are added
• how agent-facing interfaces are designed
• how the harness validates tool registration and behavior
• how changes are documented and tested

This is not a runtime requirement, but it is the best place for team-level regulation.

What belongs here

1. Tool registration rules
2. Agent-facing interface design
3. Response / error formatting requirements
4. Example and harness test expectations
5. Deployment and local agent testing workflows

Tool registration conventions

• All MCP tools must be defined under src/functions/.
• Each tool module must import src.server_instance.mcp and decorate tool entrypoints with @mcp.tool().
• The repository should keep tool registration centralized in src/main.py by importing tool modules there.
• When explicit @mcp.tool(name=..., description=...) metadata is provided, that metadata takes precedence over the function name and docstring and should be treated as the public contract.
• Example domains:
  • src/functions/celestial/impl.py
  • src/functions/telescope/impl.py
  • src/functions/metadata/impl.py
  • src/functions/planning/impl.py
  • src/functions/weather/impl.py
  • src/functions/places/impl.py
  • src/functions/time/impl.py

Agent-facing interface rules

• All tools must return JSON-serializable data.
• Public changes must preserve both the historical pre-1.0 baseline and the full 1.0 baseline (tests/public_contract_v1.json), including task annotations/models. Follow docs/v1-migration.md and docs/contract-policy.json for compatibility review and finite deprecation requirements; snapshot refreshes must not conceal drift. A contract freeze does not authorize a release. The explicitly reviewed optional weather-atmosphere extension is recorded in docs/contract-policy.json and docs/weather-atmosphere-contract.md. Its separate schema record must match exactly before projecting only those additions for historical comparison.
• Use src.response.format_response(...) for standard response wrapping.
• Business validation failures that remain inside normal tool execution should return the structured {error, _meta} payload shape instead of ad hoc dicts.
• Dates and times should be returned as ISO strings whenever possible.
• Keep tool argument names clear and stable; renames should be treated as breaking changes.
• Add new tools only after verifying the new interface is agent-friendly and documented.
• Every public tool description must include Use when:, Do not use when:, Requires:, Returns:, and Follow-up: guidance. Describe actual behavior and route common misuses to registered alternatives. Explicit decorator descriptions override function docstrings.
• Keep this guidance in the standard MCP description. The catalog retains its existing summary description and full docstring fields; an explicit description is already complete. Do not introduce a separate routing schema only visible through get_tool_catalog.