skill_compile_ide_companion_status

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

With no annotations provided, the description carries full burden and does a good job: 'no-spend' explicitly signals this operation does not consume budget/credits, and 'returns next safe MCP action' discloses it is an analysis/report tool rather than a mutating one. It communicates the key behavioral trait an agent needs (safe, non-consuming read). It doesn't mention auth or failure modes, but the core safety profile is conveyed.

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 front-loads the purpose in the first line, then delivers behavior, KB reference, and a worked example in a compact block. Every sentence earns its place; the example is genuinely illustrative. Minor redundancy exists between the prose param list and the example, but nothing is wasteful.

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 5-param tool with zero schema coverage, the description covers both the inputs and the return values, and an output schema exists to formalize returns. The KB pointer and example round out the context. The only gap is the lack of an exact session_plan structure/format, but the example plus KB anchor make this adequate.

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 0%, so the description must compensate — and it does. It enumerates the optional inputs in prose (readiness report, completed phase names, evidence map, manual blockers) mapping to the schema params (readiness_report, completed_phases, evidence, current_blockers), and confirms session_plan is required via the example. This gives meaning the bare schema lacks, though it uses slightly loose aliases rather than exact param names.

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 a specific verb+resource: 'Compile a no-spend progress receipt for an IDE companion session.' It clearly differentiates from siblings like skill_compile_ide_companion_dashboard and skill_compile_ide_companion_work_order by naming the exact output (phase states, blocking gates, evidence gaps, readiness flags, next safe MCP action). The purpose is unmistakable.

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 implies usage context — generating a status receipt during a session — with a KB reference and a concrete example. However, it never explicitly states when to prefer this over the many sibling session tools (work_order, blocker_resolution, asset_lifecycle_manifest) or when not to use it. The KB pointer substitutes for but does not provide direct 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.