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

Annotations are empty, so the description carries the full burden and it does: it discloses that credentials never surface, that reads are unrestricted while writes depend on owner-granted permissions on ecomdly, that limits live in the service skill, and that the response includes status, paging/limit headers and a possibly truncated body requiring pagination. The truncation warning alone is behavior an agent could not infer elsewhere.

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?

It is front-loaded with the core capability and every sentence carries information (credential handling, skill lookup, relative paths, read vs. write rules, truncation, sibling exclusion). The prose is dense and somewhat run-on with parentheticals, which costs a little scannability, but 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?

For a generic pass-through HTTP tool with no output schema and no annotations, the description covers what is missing: where auth comes from, which methods are permitted, how limits are discovered, what the response contains and that long bodies must be paged. An agent could call it correctly without consulting anything but api_list and the service skill it names.

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 already documents every field including the method default. The description adds the useful framing that path is relative to the service and supplies concrete Intercom examples for path and body, but largely restates what the schema already says, so it sits at the baseline rather than adding substantial meaning.

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 resource: call the API of an app the owner connected on ecomdly, with ecomdly injecting the owner's credentials. It explicitly distinguishes itself from the sibling shop_request ('E-shops go through shop_request, not here') and positions api_list and the service skill as companions, so an agent can tell which tool to reach for.

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?

Gives explicit when-to-use (reading via GET or Intercom's POST .../search always works; other methods only where the owner allowed them), names prerequisites (api_list for the app, the service's skill for paths and limits), and carves out an exclusion ('E-shops go through shop_request'). This is exactly the routing guidance an agent needs before invoking.

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