validate_gstin

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

Annotations already cover read-only and idempotent behavior. The description adds meaningful behavior beyond those: it performs checksum verification, strips spaces/hyphens from input, and explicitly disclaims live GSTN registration-status checking. This is valuable for an agent deciding whether to use this tool for a compliance workflow.

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 well-organized with clear sections (Args, Returns, Notes) and front-loads the core purpose in the first line. It has a little redundancy with the schema description, but every section contributes something practical and there is no filler.

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 the single parameter, full schema coverage, an output schema, and read-only/idempotent annotations, the description covers the essential operational context: what it validates, what it returns, when to use it, and a critical limitation. An agent can invoke this tool correctly without guessing.

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 already 100%, giving a baseline of 3. The description adds a concrete example ('27AAPFU0939F1ZV') and clarifies that spaces/hyphens are stripped despite the schema only saying they are allowed. This extra semantic detail helps the agent understand normalization behavior beyond the schema.

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 starts with a specific verb ('Validate and decode') and a specific resource ('Indian GSTIN') followed by a key behavior ('checksum verification'). It does not explicitly contrast with the closest sibling 'bulk_validate_gstin', but the singular framing and tool name make the single-item scope reasonably clear.

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?

It gives concrete triggering scenarios: 'checking supplier/customer GSTINs before invoicing, reconciliation, or compliance workflows.' It also provides an exclusion by noting that it does not verify active GSTN registration status, which tells an agent when this tool is insufficient. It does not mention alternatives such as bulk_validate_gstin for batch needs, so it falls short of explicit when-not-to-use guidance.

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