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

Annotations already carry readOnlyHint=true and idempotentHint=true, so the bar is lower, yet the description still adds substantial behavioral context: it must be called before the first reply, the agent must read the installed skill first and 'Do not guess metadata from the plugin or catalog version,' profile blocks are 'never truncated; treat these as authoritative,' digests are 'capped' and may set 'meta.truncated.*,' and there is an explicit 'Inspect one payload, not both text and structured copies' nuance. No contradiction with annotations.

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 a single dense wall of 600+ words with no paragraph breaks, the purpose is not front-loaded (the first sentence is prerequisite protocol, not the function), and there is clear redundancy — 'consult it before choosing an entityType in penny_write' appears twice and the return value is described twice ('Returns a single orientation snapshot' and later 'Returns your working inventory'). The content is high-value but poorly edited.

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?

With no output schema and six optional parameters on a complex orientation tool, the description carries full burden and succeeds: it describes return sections (profile blocks, self_improvement, rhythms.due, trackers, skills.defined, features, projects, working inventory), conditional behaviors (onboarded, saveDrought), truncation handling with drill-down paths, environment restrictions, and the effect of each optional parameter. An agent has everything needed to call it correctly on the first attempt.

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 coverage is 100%, so baseline is 3, but the description adds real semantic value beyond the schema: it clarifies why tz matters ('so the task digest's Today/Overdue counts and dueNow list are computed in the user's local time'), disambiguates projectKey ('a repository subconscious block, not a Penny Project'), and explains the reporting logic for the skill-metadata parameters ('report absent metadata as unversioned,' 'omit if missing or unversioned').

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 states a specific purpose — 'Returns a single orientation snapshot of the user's world so you begin already aware' — with a clear resource (profile blocks, rhythms, trackers, skills) and differentiates from siblings by name (penny_read for drill-down, penny_start_setup for onboarding, penny_write for entity creation). However, the purpose statement is buried deep in the text; the opening is about prerequisites, forcing the agent to read hundreds of words to extract the core function.

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?

Usage guidance is explicit and exceptional: 'Call this ONCE at the very start of every conversation, before your first substantive reply' states when, and 'Workspace-only connections cannot call this: use penny_read target:"projects" view:"scopes", then an explicit workspaceId' states when not to, with the exact alternative. It also routes conditionally to siblings ('`meta.onboarded` false → offer setup via penny_start_setup', 'drill into them with penny_read') and explains when to pass tz and projectKey.

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