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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description usefully adds that the call is free (no credit cost) and what the response contains, including the machine-consumable payload and the covering skill doc. It does not discuss auth or rate limits, but for a read-only descriptor that is a minor omission.

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?

A single front-loaded sentence with a colon-delimited list of return contents. No filler, no redundancy, and the core action precedes the payload enumeration.

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 two-parameter, read-only descriptor with no output schema, the description covers what is returned and the cost. The notable gap is not telling the agent where valid tool/method identifiers originate, which matters given a sibling tools_search exists.

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% for both parameters, so the description must carry the load. It partially does: 'one Hyreflow tool and its methods' implies the required `tool` selects the tool and the optional `method` narrows to a single method. It gives no format or sourcing hints (e.g., that tool/method names come from tools_search), so the coverage gap is only partly closed.

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?

States a specific verb (describe) and resource (a Hyreflow tool / one method), and enumerates the payload returned: expected payload, credit cost, usage notes, and covering skill document. It is clearly distinguishable from tools_execute or tools_search by intent, though it never names those siblings explicitly.

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 'tool and its methods, or one method in full' phrasing implies when to use the whole-tool form vs the method form, and 'Free' hints at cost considerations. However, it never states when to reach for this over hyreflow_tools_search or hyreflow_skill_read, leaving the routing to inference.

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