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

Annotations already convey read-only, idempotent, non-destructive behavior, so the description does not need to repeat safety traits. It adds useful behavioral context by stating the tool returns a concise brief 'without dumping the full generated artifact' and lists what the brief contains (watchouts, evidence confidence, architecture, freshness, next actions).

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?

Three compact sentences front-load the call condition, then list the return value, then provide an alternative tool and a usage constraint. No filler or redundancy.

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 read-only, two-parameter tool with an output schema, the description covers the decision context, the differentiating alternative, the output scope, and the key input constraint. Nothing needed for a correct call is missing.

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?

The schema already fully documents repo and package, including examples and a version-specific alternative tool under package. The description adds the 'exactly one' exclusivity constraint, which slightly reinforces the oneOf schema but gives no deeply new parameter semantics.

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 an explicit verb and resource: analyze a repository or package to produce a decision brief. It names concrete use cases (depend on, fork, learn from, deploy) and differentiates from the sibling get_artifact by contrasting decision brief vs file-level orientation.

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 gives clear when-to-use triggers: entering an unfamiliar repository or deciding whether to depend on/fork/learn from/deploy it. It also provides an explicit alternative: 'Use get_artifact when file-level orientation is needed,' plus the input constraint 'Pass exactly one of repo or package.'

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