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

Annotations declare a non-read-only, open-world, non-idempotent operation, and the description adds genuine side-effect context: supplying contact_email causes a human at GIX to follow up, data is shared with the team, and test=true means logged-but-not-emailed. That discloses the real consequences (outbound contact, PII propagation) that the annotations alone cannot convey.

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 text is padded with marketing repetition ('To better serve you and your user, please tell us about your user so we can cater to their needs' says nothing new) and repeats the same pitch twice. Operational details an agent actually needs — optionality, and the test flag — are stranded at the very end instead of being front-loaded.

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 13-parameter intake tool with no output schema, the description covers the essentials: what comes back (network facts, routes, latency, quote range), that only looking_for is needed, what happens when optional fields are skipped, and the follow-up/test behavior. It could be tighter about which fields unlock which outputs, but nothing critical 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?

Schema description coverage is 100%, so the schema already explains every field, including examples for looking_for, locations and bandwidth_or_fiber_count. The description merely restates the field list and adds only marginal framing (that answering more questions yields routes/latency/quotes), so the baseline 3 applies.

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 concrete statement of purpose is buried mid-text: 'Returns the GIX network facts and resources that match your need', framed as a lead-intake that also returns routes, latency and quote ranges. That is understandable, but the tool's identity overlaps heavily with siblings get_network_info and request_quote without ever naming or contrasting them, and the opening 'Welcome to GIX' / 'Say hello' framing obscures the verb.

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?

'Answer them and we return specific routes...; skip them and you still get the general facts' gives real guidance on the optional fields, and 'Our general network facts stay open to everyone' faintly implies when not to bother introducing yourself. But there is no explicit statement of when to pick this over get_network_info or request_quote, and no exclusion conditions.

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