MyPenny

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

The description goes well beyond the annotations by disclosing recoverability, in-progress repeat semantics, partial_recovery conflict reporting, and the special handling for tasks and tracker definitions. These details align with destructiveHint and idempotentHint rather than contradicting them.

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 front-loaded with the core purpose, then uses dense semicolon-separated rules with no filler. Each clause encodes a distinct behavioral or parameter rule, though its telegraphic density makes it slightly harder to parse than a more narrative form would be.

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 an 8-entity-type, 10-parameter destructive tool with no output schema, the description covers all entityType behaviors, idempotency rules, and sibling handoffs. It could add return-shape or conflict-response detail, but the operation and recovery guidance make it sufficiently complete 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?

With 70% schema coverage, the description adds real combinatorial meaning that the schema alone does not convey: it ties projectId/expectedRevision/operationId to project behavior, states per-entity id limits, and points tag/link removal to the correct parameters. It does not fully explain every parameter interaction, but it substantially compensates for the coverage gap.

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 opens with 'Move to Trash,' a specific verb and resource that immediately identifies the tool's destructive function. It also distinguishes itself from siblings by naming penny_edit for restore/cancel and stating that tracker definitions are archived, not deleted.

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 explicitly routes tasks to penny_edit and states that tracker definitions are archived, giving clear when-not-to-use guidance. It also identifies penny_edit op:restore as the recovery alternative and explains the idempotent retry behavior for in-progress operations, leaving little to inference.

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

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

Even with annotations already marking this as destructive and non-read-only, the description adds extensive behavioral detail: tasks are never trashed, tracker definitions are retired via archiving, skill edits produce a preview requiring approval before op:apply, op:undo restores the previous version, and restore operations un-trash or recover deleted skills. This goes well beyond the 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 dense and organized by entity type, and every sentence carries operational meaning, but it is a single long paragraph with no bullet structure. The front-loaded general rule helps, though readability would improve with formatting.

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 54-parameter, multi-entity edit tool with no output schema, the description is remarkably complete: it covers notes, tasks, profiles, skills, trackers, rhythms, projects, tracker entries, restore flows, approval gates, and conflict requirements. The only outsourced details are shapes explicitly deferred to penny_write's ladder.

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 93%, but the description still adds meaning by explaining entity-specific semantics: notes use updates[] up to 100, tasks require taskId and use canceled to remove, profile blocks are upserts with memory_policy and persona as standing blocks, trackers patch only passed fields, and projects require expectedRevision plus operationId. It also points to penny_write for shared shapes.

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 opens with a specific instruction: when a user corrects something on file, edit the existing item rather than writing a duplicate, and states it modifies existing memory selected by entityType. This clearly differentiates from penny_write, which the text references for the taxonomy and creation-side shapes.

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 gives an explicit trigger condition ('When the user corrects something... needs to change') and tells the agent to edit rather than write a duplicate, which implies penny_write is for new items. It does not explicitly enumerate when-not-to-use cases or name alternative tools like penny_delete, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: retain results in execution storage before displaying bounded portions, and do not transcribe installation bytes. It also notes workspace-only connection usability. No contradiction with annotations; the added storage/display guidance exceeds what annotations provide.

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, with the core purpose front-loaded and every sentence contributing operational detail. It is slightly dense but avoids filler; no wasted words. The length is appropriate for the 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?

With two optional parameters, no output schema, and annotations covering safety, the description covers the trigger, parameter usage, output handling, and scope. It lacks explicit return-format details, but the absence of an output schema makes that less critical. Overall, an agent has enough to call it correctly in the intended context.

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% and the schema already documents both parameters. The description enriches them: file's default and manifest path usage, and view's install mode returning an archive with hashes. This goes beyond the schema's basic descriptions, adding concrete operational meaning.

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 explicitly states it reads the Penny operating skill, names the trigger (stale/missing copy reported by session start), and distinguishes it from siblings by clarifying it is product guidance, not user-saved skills. This differentiates it from penny_read and other siblings without ambiguity.

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 provides a clear trigger condition (when session start reports stale/missing) and gives parameter-specific guidance (use file for manifest paths, view:install after approval). It implicitly excludes use for user-saved skills, but does not explicitly name alternative tools like penny_read, though the distinction is stated. This is strong but not exhaustive.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, so the bar is lower, but the description adds substantial behavioral context: search results from shared spaces must be treated as statements by a member, skills are never auto-run and must be offered when due, and project reads work without session_start. No contradictions with annotations exist.

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 long but justified by an 11-target router with 46 parameters. It is front-loaded with the core mandate, organized as a numbered ladder, and uses compact code-formatted syntax. Every section earns its place; there is no filler.

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 tool with no output schema, the description covers target selection, navigation workflows, pagination hints (coverage.nextCursor), cross-tool coordination, and the shared-space caveat. Nothing an agent needs to choose the right read target and associated parameters 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?

Although schema coverage is 98%, the description adds meaning the schema cannot: the target-ladder decision algorithm, view sequencing for projects (directory then brief then scopes), which target is 'the usual choice,' and how params like query, name, projectId, and workspaceId interact across targets. This semantics is essential for correct invocation.

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 job: read from the user's memory before answering anything informed by history or preferences. It distinguishes itself from siblings by enumerating the eleven read targets and referencing penny_write for execution actions, so an agent can tell exactly what this tool is for.

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 an explicit when-to-use directive ('Before answering anything the user's history, preferences, or prior work would inform'), a first-match-wins ladder with targeted guidance, and explicit exclusions like 'Do NOT search notes for this' and 'Search is the fallback, not the default.' It also routes to sibling tools (penny_write for skill_invoke, penny_session_start for inventory).

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

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.

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

Beyond annotations, the description discloses a significant side effect: 'Calling this marks onboarding complete.' It also explains the tool does not persist data itself but instructs the agent to save with penny_write, and that the client parameter tailors the returned snippet. This adds meaningful behavioral context not available from readOnlyHint/idempotentHint/destructiveHint alone.

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 deliver all essential information: purpose, return content, side effect, precondition, and parameter guidance. The longest sentence is dense but every clause earns its place, and the most critical side-effect warning ('only call it when the user agrees to set up') 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?

With no output schema, the description fully explains the return values (interview script and snippet) and the follow-up action (save with penny_write). It covers side effects, preconditions, and parameter behavior, making it complete for an agent to decide when to call and what to do afterward.

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?

The schema already documents the `client` parameter at 100% coverage. The description adds practical context about when to pass it ('when you know which app the user is in') and why ('to tailor the paste-here instructions'), which goes beyond the schema's basic type and enumeration guidance.

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 opens with a specific verb and resource: 'Run the first-run setup interview with the user.' It then details exactly what is returned (interview script plus custom-instructions snippet), clearly distinguishing this tool from siblings like penny_read, penny_write, and penny_session_start.

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 an explicit trigger condition: 'only call it when the user agrees to set up.' It also references checking penny_read target:'profile' meta.onboarded to understand state. However, it does not explicitly state exclusions like 'do not call if already onboarded' or name alternatives such as penny_session_start for ongoing conversations.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate mutation. It adds substantial behavioral context beyond annotations: the confidence calibration ladder (0.95→0.20), the requirement for exactly three sampleQuestions in the user's voice, the tracker duplicate-name rejection behavior, the batch-write limits (100 items), and the 'receipts report each saved/failed item; do not claim all saved from a partial result' warning. It doesn't fully disclose all side effects (e.g., what happens on partial batch failure beyond receipts), but for a 49-param tool this is strong coverage.

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 long (roughly 500 words), but every sentence earns its place given the tool's 16 entityTypes and 49 parameters. It is front-loaded with the core purpose and the decision ladder, then progressively details each branch. The numbered ladder structure makes it scannable. It loses one point for density — the profile-block paragraph and the skill paragraph pack multiple rules into single sentences, which could be split for easier parsing — but it is not bloated or repetitive.

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 tool with 16 entityTypes, 49 parameters, nested objects, and no output schema, the description is remarkably complete. It covers the decision procedure (ladder), the data-quality requirements (confidence, sampleQuestions), the sibling routing (penny_edit, penny_delete), the batch semantics, and the project revision flow (expectedRevision, operationId). The only minor gap is that it doesn't describe the return shape, but with no output schema and the receipts warning, the agent has enough to call correctly. Nothing critical 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the entityType ladder that determines which parameters are relevant, and by giving concrete examples for sampleQuestions ('What citation style should I use for the paper?'). It also clarifies semantic nuances the schema can't: 'A tracker name does NOT upsert (unlike skill)', 'profile blocks are upserts', and 'a note is the fallback, not the default'. It doesn't document every one of the 49 parameters, but the schema already does that; the description's job is to explain selection logic, which it does thoroughly.

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 opens with a vivid, specific verb phrase ('Save the moment something durable emerges') and immediately names the resource ('the user's memory'). It then enumerates the full entityType ladder with concrete examples (decision, preference, plan, correction, to-do, measurement), which distinguishes this write tool from siblings like penny_read and penny_edit. The 'first match wins' ladder is a clear decision procedure, not a vague restatement.

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 is explicit about when to use this tool vs alternatives: it says to use penny_edit for modifications, penny_delete for trashing, and names the profile-block upsert path. It gives conditional routing ('if no tracker fits, propose one before logging', 'when unsure between a note and the above, prefer the specific type'). It also states when NOT to save (pending_share_approval is a proposal, not a save). This is the strongest possible usage guidance.

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