Find a brand's logo

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description reinforces and extends them with the write-scope requirement, an explicit cost (~$0.007 from credit), a budget cap with default 2 / max 10, chargedUsd as the actual spend, and the web-lookup fallback for unknown small brands. No contradiction, and it adds auth, cost and fallback behaviour that the annotations do not carry.

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 establishes the deliverable and return shape before cost and auth details follow. It is dense but each clause (cost, budget cap, chargedUsd, write scope) earns its place; only the italicised cost figure feels slightly redundant with the budgetUsd sentence.

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?

With an output schema present, the description need not detail the return object, yet it still signals the handle, colour cuts and PNG key. Between annotations, the 100%-covered schema and the output schema, an agent has everything needed to call this correctly, including the billing and scope preconditions.

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 all four parameters (including 'about' and 'domain') are already documented in the schema, including the 'preferred over a web lookup' note. The description quotes the same budgetUsd defaults and the domain-over-lookup preference, adding little semantic value beyond the structured fields.

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 description names a concrete deliverable ('a company's or product's real logo, ready to place') and states what comes back (brand:<slug> handle, colour cuts, PNG media key). Against siblings like find_photo, find_footage and find_face, the agent immediately knows this is the brand-logo lookup rather than generic imagery.

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 implied usage (pass the brand name, provide domain when known, small brands fall back to a web lookup) but never states when to prefer this over find_photo, reference_search or web_search, nor any exclusion. The context is inferable but the routing decision against siblings is left to the agent.

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