Social Search Projects

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

With no annotations, the description carries the full burden. It discloses that results are a lean summary, lists the returned fields, and importantly warns that the underlying API is currently broken and failures may be an upstream issue. This gives an agent useful expectations about behavior and failure handling, though it does not mention rate limits or error shapes.

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 well-structured and front-loaded with the core purpose, followed by result format, follow-up tools, and a relevant reliability warning. The phrasing is slightly informal in places, but each part earns its place and the length is appropriate.

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 simple search/browse tool with a complete input schema and an output schema present, the description covers the main behavior, return summary, follow-up paths, and even a known upstream outage. It is sufficiently complete for an agent to call it and interpret results, though it could have explicitly stated whether the operation is read-only.

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 the input schema already fully explains sort, limit, query, offset, and language. The description adds only the browse-vs-search behavior for an empty query, which is also stated in the schema. It does not materially deepen parameter understanding beyond the structured definitions.

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 states the tool's action: search or browse Scratch's shared projects. It uses a specific verb and resource, and adds enough detail about result contents to distinguish it from the many sibling tools focused on opening, editing, or managing local projects.

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 explains when to browse versus search ('browse them when no query is given') and explicitly names follow-up tools: social_get_project_info for full records and project_download for editing. It does not exhaustively contrast against all alternative tools, but provides practical routing guidance for the main decision.

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