axint.xcode.guard

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

Annotations are mostly false (not read-only, not destructive, not idempotent). The description adds behavioural context: it writes .axint/guard proof, may start a session, and explicitly states it does not edit source or use network. This goes beyond what annotations provide, though could detail side effects more.

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 fairly concise, covering purpose, checks, use cases, and effects in about three sentences. It could be more structured (e.g., bullet points), but it is not verbose and front-loads key information.

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 14 parameters all described and an output schema present, the description covers the tool's behavior and use cases adequately. It explains what it does, when to use it, and its side effects. Some details like error handling or session start behavior could be elaborated, but overall it is sufficient.

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 baseline is 3. The description adds minimal additional meaning beyond what the schema already provides for parameters. It only generally mentions writing a report, which is already implied by the 'writeReport' parameter.

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: guarding against context compaction and Axint drift. It specifies what it checks (project memory, session, guard proof, long-task freshness) and its effects. However, it does not explicitly differentiate from siblings like axint.session.start or axint.run, though the use cases imply distinction.

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 explicit usage scenarios: 'call around long Xcode tasks, context recovery, broad Swift edits, or before claiming runtime proof.' It also notes effects and what it does not do. It lacks explicit when-not-to-use or alternative tools, but the provided use cases are clear.

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