cellc_metadata

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

With no annotations, the description bears full responsibility for behavioral disclosure. It states 'compiler-emitted metadata' and 'summary by default', but does not reveal whether the tool is read-only, any side effects, required permissions, or error behavior. This is insufficient for an agent to safely invoke the tool.

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 sentence, which is concise. It front-loads the core topic ('Compiler-emitted metadata'). However, it is too brief to be fully effective; it sacrifices necessary detail for brevity, making it less useful despite being short.

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 4 parameters, no output schema, and no annotations, the description is severely incomplete. It lacks details on parameter semantics, return format, usage context, and any constraints. An agent cannot reliably invoke this tool based on the provided information.

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 0%, so the description must compensate for missing parameter documentation. However, the description does not explain the purpose of any of the four parameters (full, path, source, target_profile). The only hint is 'summary by default', which vaguely relates to the 'full' boolean parameter, but agents cannot infer correct 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 clearly states the tool provides 'compiler-emitted metadata: resources, actions, effects, obligations' and mentions 'summary by default'. This specifies the verb (retrieve metadata) and resource (compiler-emitted metadata), and the phrase 'by default' hints at a default behavior, distinguishing it from siblings like cellc_check or cellc_explain.

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 does not provide explicit guidance on when to use this tool vs alternatives. It only implies that 'summary by default' is suitable for quick overviews, but fails to mention when to use other parameters or how to choose between siblings such as cellc_check or cellc_explain.

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