Assess org security posture

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is partly structured data. The description still adds real value beyond that: it names the controls inspected and describes the return shape (per-control pass/fail/unknown with severity and the exact remediation tool, plus a summary grade) — important because there is no output schema. It stops short of 5 by omitting any note on latency, rate limits, or how findings vary by plan level.

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?

Three sentences, each doing distinct work: what it scores, what it returns, and how it relates to the mutating sibling. Scope and the read-only guarantee are front-loaded, and there is no filler or repetition of the title.

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 single-parameter, read-only assessment tool with no output schema, the description covers the controls evaluated, the shape of results, and the follow-up path for remediation. Nothing an agent needs in order to decide to call it or to interpret the response is missing.

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?

Only one parameter exists and schema description coverage is 100%, so the schema already explains that 'org' is an organization login subject to GHE_ORG_ALLOWLIST. The description adds no further meaning about the parameter (format, case sensitivity, error behavior on a non-allowlisted org), so the documented baseline of 3 applies.

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?

States a specific verb ('Score') and resource ('an organization') and then enumerates the exact baseline controls evaluated (2FA, base permission, secret scanning + push protection, Dependabot, Actions policy). This is clearly distinguishable from the read-oriented siblings such as list_secret_scanning_alerts or get_actions_permissions, which surface raw data rather than a graded assessment.

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 explicitly routes the agent: use this to assess ('Read-only — it changes nothing') and use harden_org_settings to apply fixes. That is a clear use/alternative split. It falls short of a 5 because it never states exclusions or preconditions in prose (e.g. allowlist behavior, cost of running against large orgs), leaving some of that to the schema.

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