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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial context beyond them: the review-state flag and when it triggers, engine naming on every result, the Fast Extraction → monolith_rescue fallback with a concrete 10-minute client-timeout requirement, and the error path when both engines fail. That is exactly the runtime-behavior disclosure annotations cannot express.

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?

Front-loaded with the outcome and the differentiators, and every sentence carries operational weight (routing, trust-the-review-flag, timeout). It is a single dense block where the package-resolution detail and the sibling exclusions slightly overlap, which keeps it from a 5.

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?

An output schema exists, so return-value description is not required, yet the description still names the contract (pinout_evidence_v1) and the key fields plus the review-state semantics. Failure modes, fallback behavior, and timing expectations are all covered for a multi-minute-capable extraction tool.

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 the schema already documents documentPath (https-only vs local stdio), partName (disambiguation), and packageSelection. The description does add interpretive value by explaining that the package is resolved from the terminals and can be cross-checked against the package drawing, which reframes packageSelection as an override for multi-package datasheets rather than a required input. With full schema coverage this is at minimum a solid 3, and the added framing lifts it.

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?

Specific verb and resource: extracts a component's pin/pad table from a datasheet PDF as a PinoutEvidence document, and explicitly states it also resolves package family/variant/pin_count. That second capability is called out as a distinguishing purpose, which lets an agent separate it from extract_package_dimensions and decode_part_number without opening schemas.

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?

Explicit routing: use for package-variant and pin-count questions, not extract_package_dimensions (mechanical geometry) or decode_part_number (ordering codes), and 'Prefer this over reading the PDF yourself.' It also tells the agent to trust review.required before acting, which is a usage rule rather than a description of behavior.

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