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

Annotations already declare a safe read operation, but the description adds genuinely non-obvious behavior: the code embeds the real deployment, variant and inputs; a webhook trigger URL is included for workflows; and critically, the API key comes from the FETCH_HIVE_API_KEY environment variable, no keys or secrets are returned, and the agent must not ask the person to paste one. That security-handling guidance is exactly the kind of context annotations 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?

Front-loaded with the deliverable, then prerequisites, then the security note in priority order. The opening sentence is dense and slightly run-on with its parenthetical language list, but no sentence is wasted.

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 tool with annotations but no output schema, the description covers purpose, targeting rule, prerequisite deployment, what gets embedded in the output, and secret handling — essentially everything needed to invoke it correctly. The only marginal gap is ambiguity when both IDs are passed.

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 100% and the schema descriptions are terse ('An agent.', 'A deployed workflow.'), so the description's 'Pass workflow_id or agent_id' adds the important selection rule the schema does not express — that the two are alternative targeting modes rather than both required. It does not address what happens if both or neither are supplied.

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 and artifact: 'Ready-to-paste code (curl, TypeScript and Python)' plus the exact resource ('a deployed workflow or an agent') and the context ('from the person's own app'). This clearly separates it from execution siblings like run_workflow/run_agent, which run the thing rather than emit code for calling it.

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 scenario of use is explicit (calling from the person's own app) and it names the prerequisite sibling: 'A workflow must be deployed first (deploy_workflow).' It also tells the agent to pass either workflow_id or agent_id. It stops short of explicit exclusions (e.g. 'do not use this to actually run a workflow'), so a 4 rather than a 5.

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