instagram_search_judge

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

The description directly contradicts the annotations: annotations declare readOnlyHint: true, implying this tool does not modify any state, but the description explicitly says 'Record what you saw' and 'rescore against the persona,' which are write-like operations. The title also says 'Record judgments.' This is a clear contradiction that could mislead an agent about side effects or state changes. The description also fails to disclose potential side effects or requirements beyond the contradiction. Given the direct conflict, a score of 1 is warranted.

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 with clear sections: purpose, guidance, and argument summaries. The prose is detailed but purposeful, explaining the reasoning behind the guidance (e.g., why to report observations not verdicts) though some redundancy exists (e.g., repeating the 'source matters' point). It front-loads the core purpose and provides a concise args/returns summary. While it could be trimmed, the length is justified by the tool's complexity.

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?

The description covers the tool's inputs, the behavioral expectations, and the return values (applied, rejected, unknown_candidates, problems[], next_step). It explains key concepts like source quality and confidence, which are essential for correct usage. However, it does not mention prerequisites (e.g., a valid search_id must exist) or error handling beyond problems[]. Given the tool's complexity and the presence of an output schema (though not shown), the description is sufficiently complete for an agent to use it correctly in most scenarios.

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?

While the schema description provides 100% coverage of parameters, the description adds meaningful semantics beyond the schema. It explains the intent behind judgments: 'Report what you SAW, not how well it matched,' and elaborates on how to encode uncertainty via 'strength' and 'owner_face_confidence.' It also clarifies the meaning of source values (vision_multi vs vision_single) and their impact on ceilings. This enriches the schema's basic type definitions, providing an agent with critical guidance for correct parameter construction.

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 purpose: 'Record what you saw in bios and images, and rescore against the persona.' It specifies the verb (record/rescore), the resource (bios and images), and the context (persona scoring). This distinguishes it from other Instagram tools, which focus on retrieval or actions. The description also explains the expected behavior of recording observations rather than verdicts, which is specific to this judge tool.

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 description gives detailed guidance on how to use the tool (report observations, not verdicts; use 'strength' and 'owner_face_confidence' for uncertainty) but does not explicitly state when to use this tool versus alternatives. It does not mention any sibling tools or conditions that would route an agent to this tool instead of others like instagram_search_enrich or instagram_search_shortlist. The usage context is implied (after observations are gathered), but exclusions or alternative selection criteria are absent.

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