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

With destructiveHint=true and readOnlyHint=false already covered by annotations, the description still adds substantial behavioral context a caller needs: credits are charged at the described cost, dry_run is free, an identical rows payload replays free within ~15 minutes while a single pending row re-bills, and above-threshold calls return confirmation_required instead of executing. This is exactly the extra context the lower annotation bar rewards.

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?

Core purpose and the dry_run/credits constraint are front-loaded in the first sentence, and the dense clauses each carry distinct operational facts. It is long and clause-heavy, so it is efficient rather than elegant, but nothing is padding.

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 complex 8-parameter dispatcher with no output schema, the description covers the important return shapes: still_enriching rows with job_id/resume/job handles, _meta.pending/instruction/poll_after_s, _meta.dataset_id, _meta.replayed, and confirmation_required. Little is left unexplained, though the role of the top-level tool/method pair relative to the rows path could be clearer.

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 only 38% over 8 parameters, so the description carries real weight. It explains that rows (up to 100) substitutes for payload and method on enrichment waterfalls, clarifies dry_run's quoting behavior, and contextualizes confirm_token via the confirmation_required flow. It leaves tool and method largely undefined and only lightly touches channel beyond the schema's own description.

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 first sentence states a specific verb and resource: 'Execute a Hyreflow tool method against live data providers.' That is far more than a restatement of the name, and the following sentences sharpen the scope (waterfall vs enrichment variants, rows vs payload). It stops short of 5 because it never distinguishes itself from execution-flavored siblings such as hyreflow_enrich_run or hyreflow_workflow_run, leaving the agent to guess which runner applies.

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 solid in-tool usage rules: dry_run returns a quote, waterfall tools take only payload, enrichment waterfalls accept rows, and above-threshold calls require confirm_token. What it lacks is explicit routing guidance against alternatives (enrich_run, workflow_run, dataset_read) or a when-not-to-use statement, so the agent must infer which entry point fits.

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