score_scan

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

With no annotations, the description carries the transparency burden. It discloses key behaviors: omitted questions count as 0, the 'needs' parameter controls recommendation selection, and gaps are reported for areas below 60%. This goes beyond a simple 'calculates result' statement. It does not mention error handling or side effects, but for a pure calculation these are minimal concerns.

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 compact and well-organized: a one-line purpose, then clear argument definitions, then a concise output summary. No fluff, and the key purpose is front-loaded.

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 the tool's moderate complexity (2 params, nested objects) and that an output schema exists, the description covers all necessary input semantics and return contents. It explains thresholds, allowed values, and the role of the optional parameter, making it self-sufficient for correct invocation.

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 0%, so the description must fully explain parameters. It does: 'odpowiedzi' is a map of question numbers (1-30) to answers with allowed values (tak/czesciowo/nie/nie_wiem or 2/1/0), and 'potrzeby' is an optional map (1-12) with tak/nie values controlling recommendations. This far exceeds the schema's bare object types.

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?

Description states a clear verb ('Oblicza' = calculates) and resource ('wynik skanu' = scan result), enumerating the specific outputs (points, maturity level, per-area scores, gaps, recommendations). This distinguishes it from siblings like get_questionnaire or get_methodology, which retrieve rather than compute.

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 implies usage: it takes answers (and optionally needs) and returns a scored result, so an agent can infer it is used after collecting responses. It does not explicitly mention when not to use it or name alternatives, but the context is clear enough.

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