sapiens_gallery

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

The description discloses significant side effects beyond the annotations: publish makes the image appear in the public gallery and Pinterest feed, can create an indexable /imagem/<id> page, and returns publicPageUrl; unpublish reverts it to private. It also warns that includeBase64 is heavy, which helps the agent avoid expensive calls. No contradiction with annotations was found.

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?

The description is dense and packed with useful information, but it is written as a long uninterrupted paragraph in Portuguese. A more structured layout with sub-action bullets would improve scannability; nevertheless, every sentence contributes meaningful guidance.

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?

Given there is no output schema, the description compensates by explaining return behavior for list, get, and publish, and by describing the effects of unpublish. It also cross-references how to use the returned imageId with sapiens_image, making the tool actionable in its full workflow.

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?

Even though the schema already covers 80% of parameters, the description adds important meaning: it ties limit to 'latest N images', describes list result fields (prompt/model/url + isPublic), clarifies that imageId is required for get/publish/unpublish, and explains what publish returns. This significantly aids correct parameter usage.

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 clearly identifies the tool as managing the user's generated images, then defines four specific sub-actions (list, get, publish, unpublish) with distinct outcomes. This makes the tool's scope and each operation immediately recognizable, even distinguishing it from related tools like sapiens_image.

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 explicitly tells the agent when to use list/get (to reuse an image as reference via sapiens_image, or to show the user what they have) and when to use publish (when the user wants to make their image public). This goes beyond generic hints and provides a decision rule.

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