Fulcra MCP Server

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

Annotations already declare destructiveHint=true, so the description's key contribution is qualifying that destructiveness: this is a soft-delete whose type and recorded data remain recoverable via restore_data_type. That materially changes the agent's risk calculus. It does not mention permission requirements or what the call returns, keeping it short of a 5.

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 short sentences, front-loaded with the action and its soft-delete qualification, then the recovery path, then the eligibility constraint. 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?

With one fully documented parameter and annotations covering the safety profile, the description supplies the essential missing context (recoverability, eligibility). The only gap is any indication of what a successful call returns, which matters slightly more given there is no output schema.

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 single parameter's description already specifies the '<BaseType>/<uuid>' ID format sourced from get_data_catalog. The tool description adds nothing about the parameter, so the baseline 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 and resource ('Archive (soft-delete) a user-defined data type') and immediately clarifies the mutation's nature. It is clearly distinguishable from siblings like delete_file, delete_records, and restore_data_type.

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?

Gives a clear precondition (only user-defined types created via create_data_type or the Context app) and names restore_data_type as the inverse operation. It lacks an explicit 'use X instead when' routing statement, but the eligibility constraint effectively excludes the wrong cases.

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=true, and openWorldHint=true, so the agent knows this mutates state and has external effects. The description adds useful context about what is produced (a new outbox and an invitation code) and the sharing side effect. It does not explain what makes the operation destructive — e.g., what happens if an outbox with that label already exists — nor anything about permissions or reversibility.

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?

A single dense sentence that front-loads the creation action and puts the conditional sharing clause after the semicolon. Efficient, though the '<recipient>'s agent' phrasing is slightly awkward to parse.

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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. What is missing is the destructive dimension: the description says what gets created but not what gets overwritten or lost, which is the one thing an agent most needs before calling a destructiveHint=true tool.

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 the baseline is 3, but the description genuinely adds meaning: it ties recipient_name to the outbox label and explains the behavioral consequence of recipient_userid (the outbox is shared with exactly that user), which the schema's 'Optional exact Fulcra user ID' does not convey. inviter_name remains unexplained in the description, keeping this short of a 5.

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 verb+resource: create an outbox labeled '<recipient>'s agent' and prepare its single-person invitation code, with an optional sharing step. That is far more than a restatement of the name. However, it never distinguishes itself from the sibling tools prepare_agent_invitation and prepare_standing_agent_invitation, which an agent could easily confuse with it.

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 only conditional given is about behavior ('with recipient_userid, share the outbox with exactly that user'), not about when to choose this tool. With three closely related invitation tools in the sibling list, the absence of any routing guidance or exclusion is a real gap.

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 non-read-only, non-destructive, closed-world, so the mutation profile is covered. The description adds genuine context beyond that: the operation is reversible via archive_data_type, and the base_type choice constrains whether fields can be used at all. It does not describe what the response returns or whether an error occurs on duplicate names, which keeps it below a 5.

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?

Four short sentences, front-loaded with the purpose, then base_type selection, then follow-up tools, then reversibility. No filler despite an 11-parameter tool; each sentence carries distinct routing or constraint information.

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 11-parameter, nested-object creation tool with no output schema, the description covers the hardest decision (which base_type) and the lifecycle (record, inspect, archive). Minor gaps remain around error/duplicate handling and validation failures when fields are passed to legacy base types.

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 would be 3, but the description adds real semantic value the schema lacks: it explains the semantic distinction among base_type values (event vs metric vs legacy annotation bases) and the field-support constraint that the enum itself only hints at with "see above."

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 and resource ("Create a user-defined data type") plus the intent (track something new), and immediately disambiguates the seven-way base_type enum by explaining what event/metric mean versus the legacy annotation bases. An agent can tell this apart from update_data_type or record_data without opening a schema.

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?

Gives clear in-tool guidance for choosing a base_type ("For new tracking prefer event or metric") and flags that legacy bases take no custom fields. It also routes forward to record_data, get_data_catalog, get_records, and archive_data_type. What it omits is when NOT to use this tool — namely updating an existing type via the sibling update_data_type, or checking the catalog first to avoid duplicates.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing consequences the agent cannot infer: sharing with `data_types` is permanent and cannot be changed later, the creator is not auto-joined, and the group ID is effectively a secret because anyone who learns it can join and the owner cannot remove members. These are exactly the risk facts an agent needs before invoking a creation tool.

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?

Front-loaded with the purpose, then progressively more conditional detail, with no filler sentences. The middle sentence about `data_types` is long and compound, but each clause carries distinct behavioral information, so the density is justified rather than wasteful.

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 7-parameter mutation tool with no output schema, the description covers the consequential behaviors, membership rules, and security posture thoroughly. The only gap is the return value — the group ID is only implied by 'anyone who learns the ID', not stated as what the call yields.

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 the baseline is 3, but the description adds real semantics beyond the schema text: it explains what omitting `data_types` means (collects nothing) and that the time range bounds a read-only share that is immutable afterward. It does not clarify `friendly_id` or `responsible_entity` beyond the schema, keeping it at 4 rather than 5.

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 and resource ('Create a group of Fulcra users') plus the motivation ('to share with several people at once'). It is clearly distinguishable from sibling tools like join_group, create_share, and get_groups.

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?

Explicitly branches on the `data_types` parameter (omit = nothing shared; include = members share read-only until they leave), names the follow-up tool (`join_group`) and the alternative target (`create_share`), and states a hard gating rule: 'Only create a group the user asked for.' That is when-to-use, when-not, and alternatives all in one place.

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 the annotations, the description explains recipient behavior: recipients read by passing this user's ID as `fulcra_userid`, they can never write here, and each agent can write to its own account while reading the other's. This adds meaningful access-model context for a non-destructive but open-world mutation tool.

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 and then adds only relevant operational context. Its four sentences are compact and each contributes to understanding scope, access, or safe use.

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 nine-parameter mutation tool with rich schema coverage, the definition is mostly complete: it covers the access model, recipient semantics, and agent-to-agent workflow. It stops short of explaining share lifecycle or return behavior, and does not mention group shares or time-bounded shares, though the schema covers those details.

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 schema already documents all nine parameters. The description adds a useful folder-path example for agent coordination, but it does not meaningfully explain most parameters such as time bounds, group IDs, or share_all_data beyond what the schema provides.

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 verb and resources: share files or data types from this account with other Fulcra users. It also states the access mode, read-only, making it easy to distinguish from siblings like list_shares and delete_share.

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 a clear usage pattern for agent-to-agent coordination, including sharing a reciprocal folder, and cautions to only share what the user asked to share. It does not explicitly name when to prefer create_agent_invitation or group-oriented alternatives, so it falls short of full when/when-not guidance.

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 establish readOnlyHint=true, so the description's job is to add beyond that, which it does: it discloses that it operates on the local stdio session's stored credentials and reveals only expiry and refresh-token *presence* rather than secret values. That last point is meaningful behavioral context about data exposure. It does not cover failure modes (e.g., behavior when no credentials are stored), keeping it at 4.

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?

Two short sentences, front-loaded with the purpose and followed by the diagnostic use case. Slightly redundant phrasing between 'local session's Fulcra credentials' and 'stdio session's stored credentials,' but nothing wasteful enough to drop it below 4.

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?

There is no output schema, and the description compensates by naming what is returned: expiry and refresh-token presence. For a zero-parameter, read-only diagnostic tool this is nearly complete; only edge-case behavior (missing credentials, expired session) is unaddressed.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline of 4 applies. No misleading parameter language is present.

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 and resource ('Return info about the local session's Fulcra credentials') and narrows scope to the stdio session's stored credentials, which distinguishes it from account-level tools like get_user_info or get_fulcra_settings. It stops short of naming a sibling explicitly, so it lands at 4 rather than 5.

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?

Gives a clear use case: 'Useful for diagnosing authentication issues.' That is real guidance on when to reach for it. It does not state when not to use it or point at a specific alternative for auth debugging, so it is a 4.

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 flag destructiveHint=true, and the description adds the key mitigation: this is a SOFT delete, prior versions survive, and there is a documented restore path including how to find version IDs. That is exactly the kind of context annotations cannot convey and it materially changes how cautiously an agent treats this call.

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?

Two sentences, zero filler. The operational fact (soft delete) is front-loaded immediately after the one-line purpose, and the cross-references to restore_file and list_files are actionable rather than decorative.

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 deletion tool with a destructive hint already declared, the description supplies the missing piece — reversibility and how to exercise it. No output schema is needed for a delete confirmation, and nothing an agent requires to call this safely is absent.

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% and the single 'path' parameter is already documented as 'The full path of the file to delete.' The description adds no further syntax guidance (root-relative vs absolute, leading slash, behavior on non-existent paths), so it neither compensates nor detracts — baseline 3.

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 and resource ('Delete a file stored in the user's Fulcra account'), which cleanly separates it from siblings such as delete_records, delete_share, and archive_data_type. An agent knows exactly what is being removed and from where.

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 establishes the recovery path — 'earlier versions of the file are kept and can be restored with restore_file' — and tells the agent how to obtain version IDs via list_files with include_versions=true. It doesn't state explicit exclusions (e.g., when to prefer delete_records), but the context is clear enough to pick correctly.

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 the destructiveHint annotation, the description discloses key behavioral traits: deletions propagate to shared users within about a minute, previously read copies may persist, and only the user's own v1 data types are affected. This is exactly the kind of contextual risk information an agent needs for a destructive mutation.

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 three tight sentences: purpose first, ID provenance second, deletion effects third. Every sentence adds actionable information with no repetition or 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 destructive tool with no output schema but clear annotations, the description covers what is deleted, which IDs to use, ownership constraints, visibility timing, and shared-user impact. No critical call-time context 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 coverage is 100%, so the baseline is 3, but the description adds useful provenance for record_ids by explaining they are the IDs returned by get_records and record_data. The data_type parameter is also tied to the user's own v1 data types, reinforcing schema semantics.

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 uses a specific verb and resource ('Delete records') and scopes it to 'one of the user's own v1 data types,' which clearly distinguishes it from file/share deletion siblings. It also names related tools (get_records, record_data) to anchor the operation.

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 clearly explains the context for use by specifying that record IDs come from get_records or record_data, and that the data type must be owned by the user. It does not explicitly compare against alternatives such as archive_data_type, so it falls 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 destructiveHint=true and readOnlyHint=false. The description adds useful behavioral context beyond that, including that deleting an outgoing share revokes every recipient's access and that a group-based incoming share cannot be given up individually. It could say more about permanence or whether recipients are notified, but its extra context is meaningful.

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 and efficient. Every sentence carries operational meaning, and the parenthetical alternative is placed immediately after the relevant limitation.

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 destructive tool with full schema coverage and annotations, the description covers the key behavioral consequences and the main usage alternative. No output schema exists, so there is no need to describe return values.

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%, and the single parameter is already fully documented as coming from list_shares, with datashare_id for outgoing shares and grant_id for incoming shares. The description complements this by explaining the outgoing/incoming distinction, but it does not add parameter-level syntax beyond the schema.

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: 'End a share'. It then clearly distinguishes the two supported operations: deleting an outgoing share versus giving up an incoming share. This lets an agent understand the tool's purpose without opening the schema.

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 explains when to use each mode: delete a share this user made, or give up a share another user shares with this user. It also names an exclusion and alternative for group-based shares: 'leave the group instead (leave_group)'. This is strong routing guidance.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds useful behavioral context beyond that: it stops sharing, verifies no grant remains, optionally archives while retaining records, and notes restore_data_type can undo the archive and that the peer's share remains unchanged.

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 compact, front-loaded sentence covering the primary action, verification, optional archive, undo path, and peer-share caveat. The final clause is slightly ambiguous, but 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?

Given the annotations, full schema coverage, and output schema, the description is largely complete: it covers the mutation, archive option, undo path, and peer-share effect. It could be fuller about authorization or return behavior, but those are partly covered by structured fields.

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 describes data_type as an owned Event/<uuid> channel, peer_userid as the exact sole authorized peer UUID, and archive as retaining records. The description reinforces the single-peer Event-channel scope and peer-share behavior, but adds little parameter-level syntax or format detail beyond the schema.

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 action and resource: stopping sharing of an owned single-peer Event channel. The mention of verifying no grant remains and the restore_data_type undo path distinguishes it from generic share or data-type operations, though the contact-level framing could be slightly clearer.

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 implies usage by describing the action and an optional archive behavior, and it names restore_data_type as the undo alternative. However, it does not explicitly say when to choose this tool over sibling share or contact operations, nor does it state prerequisites or exclusions.

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=true, destructiveHint=false, and a closed-world scope, so safety is covered. The description adds non-obvious behavior beyond that: the output switches to a calendar list when no range is given, every event carries a participant_count, and participants are omitted unless explicitly requested. It does not mention result caps, pagination, or max range size, which keeps it at 4.

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?

Two short sentences, front-loaded with the primary capability and with the participant hint placed after. The participant guidance slightly overlaps the schema's own parameter description, a minor redundancy, but nothing is wasted.

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 does the work of explaining both possible return shapes and the participant_count field, which is the key information an agent needs. All parameters are optional and schema-documented, so the remaining gaps (pagination, ordering, timezone defaults) are modest rather than blocking.

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 all five parameters are already documented in the schema, establishing a baseline of 3. The description adds rationale for include_participants ('when you need who was invited and their responses') and links the no-range case to the calendar listing, but says nothing extra about start_time/end_time exclusivity or the fulcra_userid sharing caveat.

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 and resource (get the user's calendar events) and explicitly covers both operating modes: a time-range query versus a no-range listing of calendars grouped by account/source. No sibling tool touches calendars, so no differentiation is needed, and the dual-mode framing is precise enough to predict the output shape.

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?

Gives clear conditional guidance: supply a range to get events, omit it to get calendars, and set include_participants=true when attendee identities/responses are needed. It lacks explicit when-not guidance (e.g., preferred alternatives for other time sources like get_sleep or get_location), so it stops 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 this as a safe read-only operation, and the description adds useful behavioral context: the return values are global configuration merged with contact overrides, and they are configuration values rather than instructions. It does not cover auth/rate-limit details, but that is a minor gap given the annotations and output schema.

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 two short sentences with no wasted text, and the core purpose is front-loaded before the important return-value clarification.

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 output schema and annotations carry much of the burden, and the description usefully explains merge behavior and return type. However, with 0% schema description coverage on three parameters, the description should do more to explain how `data_type` and `expected_peer_userids` affect the result.

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% for three parameters. The description vaguely implies `peer_userid` by referring to a connection/peer, but it does not explain `data_type` or `expected_peer_userids`, leaving most parameter meaning undocumented.

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 read operation on a specific resource: effective preferences for a contact/peer. It is distinguishable from the write-oriented sibling `set_contact_preferences`, though it does not explicitly name that sibling as an alternative.

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 by saying this reads effective preferences for one of your own connections. It does not explicitly state when to use this instead of `set_contact_preferences` or other settings-related siblings, so the guidance remains implicit.

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=true and openWorldHint=false, so the safety profile is covered. The description still adds non-obvious behavior: results are grouped by MCP tool, the payload includes user-defined types and annotations plus device measurements, and shared types expose a foreign fulcra_userid for reading other users' data. Minor gap: nothing about result size or whether the catalog is paginated.

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?

Two tight paragraphs, front-loaded with what the tool returns, followed by the call-ordering rule and the sharing caveat. No restatement of the name or title and no filler sentences.

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 four optional filter parameters all documented and no output schema, the description carries the return-shape burden and does so at the level of the group/type structure. It stops short of describing the per-entry fields or how large the catalog response is, but an agent has enough to call it correctly and interpret the grouping.

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 the per-parameter baseline is 3. The description adds real semantics beyond that on fulcra_userid: types shared by another user carry that user's ID and passing it reads their data — a behavioral consequence the schema only hints at ('Only the types this Fulcra user shares with you').

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 and resource ('Get all data types available for this user') plus the organizing structure ('grouped by relevant MCP tool') and enumerates the included content areas: location, events, user-defined types, annotations, device measurements. This clearly separates it from the mutation siblings (create/update/archive/restore_data_type) and from consumers like get_time_series and get_records.

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?

Gives an explicit prerequisite workflow: 'Call this before requesting time-series data or raw records,' which points the agent at get_time_series and get_records as downstream tools. It also adds a hard constraint — only use a data type with the tools named in its group — and explains the cross-user case where a type carries another user's fulcra_userid.

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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the genuinely non-obvious behavioral fact that the window filters on processing/sync time rather than record timestamps, with a concrete sleep-record example. It stops short of describing the shape of the summary returned (counts vs. per-type breakdown), which is the one remaining gap for a no-output-schema tool.

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?

Purpose first, then the semantic caveat, then the intended follow-up action. Two short paragraphs, no filler, and the most error-prone detail (time-range meaning) is given its own emphasized block.

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 read-only discovery tool with four fully documented parameters and no output schema, the description covers when to call it, what the parameters mean semantically, and what to do next. Only the return structure is left implicit, which is a minor omission since the include_shared field documents the added keys.

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 3 would be the baseline, but the description adds meaning the schema cannot: start_time/end_time mean ingestion time, not event time. That reframing is the single most important parameter semantic for correct invocation and it is stated clearly.

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 and resource: "Summarize the data that arrived in the user's account during a period of time." It also positions itself against the fetch siblings by naming the follow-up step ("query the changed types with the appropriate tools"), so an agent can distinguish this discovery tool from get_records/get_time_series without inspecting schemas.

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?

Explicitly prescribes the workflow: use this to find out what new data exists since a previous check, then query the changed types with the appropriate tools. It also sets a clear boundary by declaring what the time range does NOT mean, which is exactly the mistake an agent would otherwise make.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a non-trivial behavioral warning — that returned values are configuration, not directives — which guards against misinterpreting the payload as instructions. It stops short of describing scope or freshness of the values.

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?

A single front-loaded sentence with the verb and resource first and the clarifying caveat second. Zero waste.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile for a zero-parameter read. The remaining gap is scope: the description does not say what settings are covered or how this differs from get_contact_preferences, which is the main ambiguity an agent faces.

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 tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly says nothing extraneous about parameters.

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 ('Read') and resource ('global contact preferences'), and clarifies the nature of the payload ('configuration values, not instructions'). However, it does not distinguish itself from the closely named sibling get_contact_preferences or explain how it relates to update_fulcra_settings, leaving an agent to infer the boundary.

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 read framing implies when to use it, and 'configuration values, not instructions' hints at how to treat the result, but there is no explicit when-to-use guidance or named alternative. With get_contact_preferences and update_fulcra_settings in the sibling list, the agent gets no routing help.

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 readOnly and non-destructive, so the description is not burdened with safety details. It adds useful behavioral context: lists public and owned groups with long-form fields omitted, private joined groups appear only with subscribed_only, and group_id returns the complete record.

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, front-loaded with purpose and void of filler. The middle explanation is necessary for understanding listing behavior, though it could be slightly more compact.

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 read-only list/get tool with full annotations and no output schema, the description covers what is returned and how filtering works. An agent has enough information to invoke it correctly.

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. The description adds nuance beyond the schema: private groups the user joined appear only with subscribed_only, and group_id returns full detail, which clarifies the filtering behavior.

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 specific verbs (List, get) and resource (Fulcra groups), and clearly distinguishes between listing multiple groups and retrieving a single group by ID. An agent can differentiate it from siblings like create_group or join_group.

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?

Explains when to use listing vs single-group retrieval, and mentions sharing via create_share. However, it does not explicitly compare with alternatives like get_user_info for user lists, leaving some inference to the agent.

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 this as a safe read-only operation with no destructive behavior. The description adds useful behavioral context beyond annotations: result timestamps include time zones, and agents should translate them to the user's local time zone when known. It does not cover pagination or error behavior, but that is less critical for a read-only lookup tool.

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, compact, and free of filler. Every sentence contributes either mode clarification or time-zone handling guidance.

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 nine parameters but complete schema descriptions and read-only annotations, the description is largely sufficient. It covers the moment/range distinction and timestamp time-zone handling, though without an output schema it could say a bit more about the returned location payload.

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 schema already documents all nine parameters thoroughly. The description reinforces the meaning of `time`, `start_time`, `end_time`, and `sample_rate`, but adds little parameter-level detail beyond what the schema provides.

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 verb and resource ("Get where the user was") and clearly distinguishes the two supported modes: a single moment versus a range. It does not explicitly contrast itself with neighboring retrieval tools such as get_time_series or get_records, so it stops short of full sibling differentiation.

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 clearly explains the two usage modes: use `time` for a moment and `start_time`/`end_time` for a range sampled every `sample_rate` seconds. It does not name alternatives or when-not conditions, but the mode selection context is explicit.

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=true and destructiveHint=false, so safety is covered. The description adds the discovery behavior of the omitted-ID case, but says nothing about what the private configuration contains or any permission requirements for reading it.

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?

A single tight sentence with the main action front-loaded and the discovery mode appended after the semicolon. No wasted words, though the phrasing is compressed to the point of slight ambiguity.

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?

An output schema exists, so return values need not be described, and the tool has one optional parameter whose two modes are both addressed. Only the meaning of 'check configuration' itself is left unexplained, a minor gap for a simple read tool.

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 carry the semantics of configuration_id. It does explain that omitting it enumerates choices, which adds real meaning beyond the schema's default=null, but it never says what a valid ID looks like or what happens with an invalid one.

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 ('Read') and resource ('private check configuration'), but the resource remains ambiguous — nothing explains what a 'check configuration' is or how it relates to the tool name 'message check status'. No sibling overlaps, so differentiation is not the issue, but the purpose stays vague.

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 clause 'omit the ID to discover choices' is an explicit usage pattern for the no-argument case, which is genuinely useful. However, there is no guidance on when to supply an ID versus discover, nor any mention of alternatives or prerequisites.

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 the readOnly/non-destructive annotations, it discloses that the API endpoint is chosen automatically per type, that overlap/intersection semantics apply to range-covering records, that results are raw samples possibly drawn from multiple sources and may overlap, and that timestamps carry time zones needing conversion. That is exactly the kind of behavior an agent cannot infer from 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 core behavior and the latest-mode rule are front-loaded in the first two sentences, with nuance (overlap, raw vs. calculated, timezone) following. No sentence is filler; each carries an operational constraint the agent would otherwise get wrong.

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?

There is no output schema, so the description carries return-value semantics itself — raw sample shape, possible multi-source overlap, and tz-bearing timestamps — and it does so. Combined with a fully documented input schema and read-only annotations, nothing needed to invoke this correctly 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 coverage is 100%, so the baseline is 3; the description goes further by explaining the interaction between latest=true and omitting both dates, and by noting data_type accepts user-defined '<BaseType>/<uuid>' IDs — detail the schema only alludes to. It does not restate start/end exclusivity or the timezone format requirement, so it stops short of a 5.

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+resource ('retrieve raw records') plus two distinct modes (date range vs. latest-only), and explicitly contrasts itself with get_time_series for calculated values. An agent can distinguish it from get_time_series and get_data_updates without opening a schema.

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?

Gives explicit when-to-use rules: 'Set latest=true and omit both dates for a single latest v1 record' and 'for calculated per-interval values of numeric data types, prefer get_time_series'. It also names get_data_catalog as the prerequisite for the data_type value, so the call ordering is unambiguous.

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?

It adds crucial domain behavior beyond annotations by explaining the data handling logic (extending the range across midnight) and providing a legend for the integer codes representing sleep stages. This level of detail significantly aids correct interpretation of the data.

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 structure is excellent, using bullet points and clear, functional language to convey complex options efficiently. Every sentence directly contributes to guiding the agent on how to invoke the tool correctly.

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 is extremely thorough, covering not only the structural output (detail levels) but also the temporal data constraints (cross-midnight extension) and the underlying biological data representation (stage codes).

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 100%, the description adds necessary semantic depth by explaining the purpose of the 'level' enum choices and defining the specific values for the 'stages' array parameter.

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 purpose (returning user's sleep) and immediately distinguishes its core capability: providing sleep data at three distinct, clearly defined levels of granularity ('aggregate', 'cycles', 'stages').

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 strong internal logic for usage, specifically detailing that 'aggregate' should be used for 'multi-day questions.' While it doesn't mention alternatives, it guides the agent on the appropriate choice of level based on the complexity of the required data.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: only catalog-listed types work, result timestamps include time zones, and callers should translate to the user's local time when known. It does not describe return shape or pagination, keeping it from a 5.

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 tight sentences, front-loaded with purpose and followed by eligibility constraints and timestamp handling advice. Every sentence adds useful information with 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 read-only tool with seven well-described parameters and safety annotations, the description covers purpose, supported data types, fallback behavior, and time zone handling. Because there is no output schema, the response shape is only implied rather than fully described, so it is strong but not maximally complete.

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 schema already documents all seven parameters, including time zone requirements for start_time and end_time. The description does not add parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

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, resource, and scope: 'Get calculated per-interval time-series values for a single data type.' It also distinguishes this tool from get_records for unsupported data types, so an agent can select it without opening the schema.

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?

Explicitly says only data types listed by get_data_catalog as usable with this tool are supported, and directs other types to get_records. This gives clear when-to-use and when-not-to-use guidance with a named alternative.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds that the tool returns user references such as time zone and calendar ids, which is useful context about scope, but it does not elaborate on response structure or any behavioral traits 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 two short sentences and front-loads the main purpose. It is appropriately sized, though the phrase 'general info' is slightly redundant with the following examples of returned data.

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 no parameters, the description carries the burden of explaining return values. It lists a few example fields but leaves 'other metadata' vague, so an agent knows the general shape but not the full set of returned information.

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 tool has zero parameters, so there is no parameter semantics to document. The baseline for zero-parameter tools is 4, and the description does not introduce any confusing parameter-related claims.

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 clear verb and resource: return general info about the Fulcra user. It gives examples of the data returned (time zone, calendar ids, metadata), but does not differentiate this from sibling tools like get_fulcra_settings or debug_token_info, leaving some ambiguity about scope.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or sibling tools that might also return user-related information, so the agent must infer usage from the name alone.

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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: result timestamps carry time zones and must be translated to the user's local zone, which is an output-handling instruction an agent would otherwise get wrong. It does not mention result caps or pagination, keeping it from a 5.

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?

Two sentences, zero padding, with the core purpose front-loaded and the timezone handling note following as a distinct, actionable instruction.

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 does at least tell the agent what to expect about timestamp formatting, and all three params are covered by the schema. It leaves open the shape of a workout record (fields, volume of results, ordering), which would matter for a data-returning tool with no output schema.

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 start_time, end_time, and fulcra_userid are already fully documented, including the ISO8601 tz requirement. The description's 'period of time' phrasing restates the schema rather than adding syntax or constraint detail, so the baseline 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 and resource ('Get details about the workouts') plus the scope ('during a period of time'), which cleanly separates it from siblings like get_sleep, get_location, and get_calendar_events. It stops short of explicitly naming those alternatives, so it earns a 4 rather than a 5.

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 never says when to reach for this tool versus get_records, get_time_series, or get_data_updates, all of which can also return time-ranged data. The time-window framing implies the use case but provides no exclusions or prerequisites.

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, it discloses important behavior: members can receive group shares, joining may share listed data types read-only with the owner until the user leaves, and anyone with the group ID can join. This is exactly the kind of contextual risk and permission information an agent needs.

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 action and then adds necessary caveats and prerequisites. It is slightly longer than minimal but every sentence provides useful context.

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 one-parameter mutation with no output schema, the description covers the prerequisite user request, the required display of group details, the sharing consequences, and the related leave_group action. Nothing essential 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 coverage is 100%, so the single group_id parameter is already well documented in the schema. The description reinforces that the ID should come from get_groups, but adds no new syntax or format detail beyond the schema.

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 uses a specific verb and resource: "Join a Fulcra group." It also distinguishes this action from sibling tools by referencing get_groups for details and leave_group for undoing membership.

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 explicit usage conditions: join only on the user's behalf and at their explicit request, and show the user the group's details first. It also explains the consequence of joining when the group lists data types.

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 flag destructiveHint=true but say nothing specific; the description explains exactly what each mode does — leaving stops sharing data types with the owner and stops receiving group shares, while delete permanently removes every member and requires ownership. This is rich consequence disclosure well beyond the annotation flag.

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?

Front-loads the core action, then layers the behavioral detail and the delete caveat. Two tight paragraphs with zero filler; every sentence carries distinct information.

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 destructive, owner-sensitive two-parameter tool with no output schema, the description covers purpose, both operating modes, consequences, and the guardrail on deletion. An agent has everything needed to invoke it correctly.

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 meaning to the `delete` flag beyond the schema: it removes every member, is permanent, requires ownership, and should only be used on explicit request. group_id is left to the schema, which already documents it.

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+resource ('Leave a Fulcra group') and immediately distinguishes the leave vs delete variants. An agent can tell this apart from join_group, create_group, and get_groups without opening a schema.

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?

Explicit usage context: 'at their explicit request' and 'only when the user asks to delete it' clearly constrain when the destructive delete variant should fire. It doesn't name sibling tools as alternatives, but the verb makes the join/create distinction self-evident.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about shared-user visibility and agent-to-agent file passing, but it does not disclose ordering, pagination, or response shape for a list operation.

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 definition is front-loaded with the core purpose and uses two short paragraphs with no repetition. Every sentence adds either scope or useful workflow context.

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 could say more about what a listing returns, such as file metadata or path structure. Still, for a simple read-only listing tool with fully documented parameters and safety annotations, it provides enough context to call the tool correctly.

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 schema already documents path, fulcra_userid, and include_versions thoroughly, including defaults and constraints. The description does not add syntax or semantic detail beyond what the schema provides, making the baseline 3 appropriate.

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 verb and resource: list files in the user's Fulcra account or files shared by another user. It also distinguishes the tool from read_file and write_file by explaining the inter-agent workflow, so an agent can tell what this tool is for without opening the schema.

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 clear usage context by explaining that files pass data between agents, one writes with write_file, others notice via get_data_updates, and read with read_file. However, it does not explicitly state when to choose list_files over alternatives like read_file, open_file_manager, or get_records, so it lacks explicit exclusions.

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 readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that: the shape of the result (incoming vs outgoing entries), the meaning of `group_id`, and the fact that the user's own ID is returned so others can share with 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?

Four short sentences, scope stated first, then interpretation of results. The parenthetical about passing `sharing_fulcra_userid` is dense but earns its place; nothing is padded.

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 a single optional parameter, no output schema, and safety covered by annotations, the description carries the needed load by explaining what entries mean and what identifiers come back. A note on ordering or volume of results would close the remaining gap, but 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 coverage is 100% and the `direction` enum is fully documented in the schema, so the baseline is 3. The description's mention of "incoming entries" loosely ties to the `incoming` value but adds no format or default detail beyond the schema.

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 - listing shares both sent and received by this user - which is unambiguous. It clearly distinguishes this read operation from the mutation siblings create_share/delete_share by describing scope, though it never names those siblings as alternatives.

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 concrete downstream guidance: incoming entries are read by passing `sharing_fulcra_userid` as `fulcra_userid` to the file and data tools, and a `group_id` points the agent at `get_groups`. That routes the agent correctly after the call, but it offers no explicit statement of when to pick this over other listing tools or any exclusions.

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 the annotations, the description adds important behavioral constraints: authenticated owner verification, individual copies for open invitations, display-only labels, consent requirements, and no sends or preference changes. It still does not explain what destructive state change justifies destructiveHint=true.

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 core matching action is front-loaded and every sentence appears to add a specific constraint. The wording is dense and jargon-heavy, making it harder to scan than ideal, but there is little obvious 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?

With an output schema and rich annotations, the description need not explain return values. However, it still leaves the plain-language outcome of 'matching' unclear and never describes the destructive action implied by the annotations.

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 tool has zero parameters, so there is no parameter semantics burden. Schema coverage is also 100%, and the description does not need to compensate for missing parameter documentation.

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 gives a specific verb and resource: matching invitation codes for user-prepared invitations. It also distinguishes the operation from sender-claim-based matching and explicitly excludes sends, but it never names or contrasts the prepare/create invitation siblings.

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 is only implied through conditions like 'unambiguous FIRST-message codes' and 'not sender claims.' There is no explicit when-to-use guidance, no named alternatives, and no statement of when not to call it.

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=true, destructiveHint=false, openWorldHint=false, so 'Read-only' is largely redundant. What the description does add is genuinely useful behavior: the no-argument call yields the list plus an Invite affordance, and 'Names are not IDs' warns about a common failure mode. It stops short of saying what the panel shows or whether it has side effects.

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, no filler, and the read-only safety note is short. The opening clause 'Open Agents I Know as a full panel' is awkward and slightly opaque, and the URI-resolution guidance is compressed to the point of ambiguity.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile; the description correctly focuses on parameterization and default behavior. It is still incomplete on the one thing an agent most needs, the distinction from open_agent_contacts_home and the other contact tools in the sibling set.

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 carries the full burden and does so: it explains that both thread_id and peer_fulcra_userid must be exact identifiers, that they are alternatives for pinpointing one contact, and that names cannot be substituted. The 'resolve contacts://threads/id-' instruction is the only unclear piece, but overall both parameters gain real meaning beyond the bare anyOf string schema.

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 verb 'Open' plus the object 'Agents I Know as a full panel' establishes that this surfaces a UI panel rather than a data query, and 'omit IDs for the list and Invite someone' hints at the default view. However, the near-identical sibling open_agent_contacts_home is never mentioned, so an agent cannot tell them apart, and 'full panel' is loose phrasing for what is opened.

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 conditional guidance for the parameter cases ('omit IDs for the list', 'for an exact contact ... pass its exact peer_fulcra_userid or discovered multiparty thread_id'). What it never states is when to choose this over open_agent_contacts_home or search_agent_contacts, which is the real routing decision for an agent facing 50 siblings.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuine context beyond that — it preselects the first available contact rather than opening an empty view — but says nothing about what happens when no contacts exist or what the call actually returns to the agent.

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?

A single short sentence with zero filler, front-loaded on the verb and resource. Every clause earns its place by adding the preselection behavior.

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?

An output schema exists, so return values need not be explained, and a zero-param read-only navigation tool has a low bar. What remains thin is the edge-case behavior (empty contact list) and the relationship to the sibling contacts tools.

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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of "first available contact" implicitly clarifies that selection is automatic rather than caller-specified, which is a small plus.

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 (Open) and a named resource/view ("Agents I Know"), plus the side effect of preselecting the first available contact. It is distinguishable from the generic open_agent_contacts sibling by the named view, though the description never says how the two differ.

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 is only implied: opening a named contact view suggests navigating to the contacts UI, but there is no explicit when-to-use, no when-not-to-use, and no reference to the obvious alternatives (open_agent_contacts, search_agent_contacts, open_file_manager) even though they appear as siblings.

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=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that this surfaces an interactive UI to the user and accepts any file type or size, which is useful context beyond the annotations. However, it omits the key behavioral trait an agent needs: whether the call blocks pending user interaction and what it returns (a path? a handle?) once the user uploads or downloads.

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?

Two front-loaded sentences, no filler. The parenthetical 'any type or size, such as spreadsheets' is a slightly incidental detail but it does convey a real capability, so it earns its place.

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 2-param, no-output-schema tool with annotations, the description covers what the tool is but not the interaction model, which is the crux of a UI-opening tool: whether it blocks, what the agent should do afterwards, and how the resulting files relate to list_files. Adequate but with a clear gap for this tool's complexity archetype.

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%, and the schema already explains 'path' (folder or exact file, default "/") and 'fulcra_userid' (file owner, shared files are read-only, separate share still required). The description adds nothing about either parameter, so the baseline 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 and resource: 'Show the user a file manager for their Fulcra files', and adds scope (upload from computer, download). It does not name or distinguish itself from the many headless file siblings (list_files, read_file, write_file, start_file_upload, upload_file_chunk), so an agent must infer that 'show the user' means an interactive UI rather than a programmatic operation.

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?

'Use it when the user wants to upload or download files' gives a trigger condition, but it overlaps directly with start_file_upload/upload_file_chunk/write_file/read_file, which also serve upload and download intents. No exclusion or preference rule is given (e.g. 'use this only for interactive/bulk/ad-hoc transfers; use upload_file_chunk for scripted uploads'), leaving a real misroute risk.

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 destructiveHint=false and openWorldHint=false, and the description adds useful constraints (never invent codes, use the returned topic exactly). However, the instruction to 'Include own_userid/code in the invite' references inputs that do not exist in the schema, which muddies rather than clarifies behavior.

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?

Short and front-loaded with the purpose, but sentences are terse to the point of cryptic ('authorizes only its matched return share') and include off-schema references that consume attention without adding usable instruction.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. Still, the mismatch between described inputs (own_userid/code) and actual parameters leaves an agent uncertain how to construct a valid call.

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 the schema already explains data_type and open_invitation. The description adds no real semantics for either parameter and instead mentions own_userid/code, which is not a parameter at all.

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?

Specific verb+resource: 'Prepare an invitation code', with scope clarified as 'authorizes only its matched return share'. However, it never distinguishes itself from siblings like create_agent_invitation or prepare_standing_agent_invitation, so it stops short of a 5.

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?

'at the user's request' implies a usage context, and the 'accepting agent's FIRST message' line describes downstream consumption. But there is no explicit when-to-use versus the closely named sibling invitation tools, leaving the choice 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?

The description usefully discloses that the invitation is created implicitly on first use, that it is private and never shared, and that responders get isolated outboxes via matching — context the annotations do not convey. However, destructiveHint=true and readOnlyHint=false are only partially accounted for: the only mutation the description hints at is creation, while the schema's clearing behavior ("" empties the saved name) and its effect are never explained in prose.

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?

Two short sentences, front-loaded with the resource and its most important property (private, never shared). The parenthetical is dense but earns its space; nothing is padded.

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?

An output schema exists, so return values need not be explained, and privacy/creation semantics are covered. But for a destructive, non-readonly tool in a large invitation-flow family, the description leaves out the side effects of clearing the name and any routing rules to the sibling invitation tools.

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 single parameter's description already covers the set/clear/keep semantics for inviter_name, so the description need not repeat it. It adds nothing about the parameter, which is acceptable given full schema documentation.

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 the resource and the key behavior ('standing open invitation', created on first use, private), but the verb 'Get' sits awkwardly against the tool name 'prepare' and the non-readOnly annotation. It never distinguishes this from the several closely related siblings (prepare_agent_invitation, create_agent_invitation, match_agent_invitations), which an agent will be choosing between.

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?

There is no statement of when to call this versus prepare_agent_invitation, create_agent_invitation, or match_agent_invitations, and no preconditions are given. The agent must infer call conditions from the name alone in a crowded invitation-flow family.

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=true and destructiveHint=false, so safety is covered; the description adds genuinely non-obvious behavior beyond that: spreadsheets are returned as CSV with one section per sheet, and the cross-user sharing scope. It omits the truncation-by-default and base64 behaviors, but those are documented in the schema fields.

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?

Two sentences, both front-loaded with the primary action first and the format caveat second. Nothing is wasted and there is no restating 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 read-only tool with full schema coverage and annotations, the description covers source scope and the one surprising return-format behavior. A brief note on default truncation or that binary content is opt-in would make it complete, but the schema already carries those details.

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 all five parameters (path, as_link, max_bytes, fulcra_userid, include_binary) are already fully explained in the schema. The description's clause about another user's shared files loosely corresponds to fulcra_userid but adds no syntax or format detail. Baseline 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+resource ('Read a file from the user's Fulcra account, or one another user shares'), which is enough to separate it from list_files/write_file/delete_file by operation. It stops short of explicitly naming those siblings, but the resource scope (shared vs. own files) is stated precisely.

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 is implied by the verb — read a file when you need its contents — but there is no explicit when-to-use guidance (e.g. when to call read_file vs. list_files to discover a path, or when to use open_file_manager). No exclusions or alternatives are named.

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?

With destructiveHint=false and readOnlyHint=false, the annotations already say this is a non-destructive write. The description adds genuine behavioral context beyond that: v1 types (including user-defined Event/Metric) return the new record's id, which get_records exposes as `id` and delete_records consumes. It does not mention auth or rate limits, but for a simple append-style write this is adequate.

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?

Front-loaded with the action, then the workflow routing, then return-value semantics. Four short sentences with no padding, though the opening line repeats the tool name awkwardly.

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?

No output schema exists, and the description fills that gap by explaining what comes back (the record id for v1 types) and how downstream tools use it. For an 8-parameter tool at full schema coverage, the only real omission is error/retry behavior, which the `record_id` schema field already handles.

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 the baseline is 3; the description earns above baseline by specifying the '<BaseType>/<uuid>' ID form for user-defined types, which the `data_type` schema field does not say. It does not add anything about note, tags, or start/end_time beyond the schema.

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 (record) and resource (a single record of a data type), which an agent can distinguish from read/write siblings like get_records or write_file. The phrasing 'record a single record for a recordable data type' is slightly circular but the scope (single record, write) is unmistakable.

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?

Routes the agent through the workflow explicitly: get_data_catalog to find types, create_data_type for new ones, get_records to read back, delete_records for the returned id. It gives no condition for when NOT to use it (e.g., bulk vs single, versus write_file), so the exclusions are implicit.

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 disclose that this is a non-read-only, non-destructive, closed-world mutation. The description adds the meaningful precondition that the target must be archived, but it does not cover permissions, idempotency, error behavior, or what restoration entails.

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 front-loaded sentence with no redundant or filler content. It is appropriately sized for a simple one-parameter operation.

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 low-complexity mutation with one fully documented parameter and annotations covering safety, the description is minimally adequate. It omits expected outcomes and failure conditions, which would help an agent invoke it confidently.

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%, and the single parameter's format and meaning are fully documented in the schema. The description provides no additional parameter semantics beyond the schema.

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 verb and resource ('Restore an archived user-defined data type'), making the operation clear. It does not explicitly differentiate from siblings such as archive_data_type or restore_file, but the resource and archived-state qualifier provide adequate clarity.

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 word 'archived' implies the tool should be used only on archived types, giving minimal usage context. It does not explicitly state when to use this instead of alternatives or what happens if the type is not archived.

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 and openWorldHint=false, so the agent knows this mutates the account but is framed as non-destructive. The description adds the versioning semantics ('a previous version'), implying version history is preserved, but says nothing about whether current file content is overwritten, whether the old head remains recoverable, or whether new versions are created.

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?

A single front-loaded sentence with no filler; the verb and resource arrive immediately. It is arguably under-specified rather than padded, so the efficiency is real but leaves value on the table.

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 one-parameter mutation tool with no output schema and full schema coverage, the description covers the core action and annotations cover the safety profile. It stops short of explaining the effect on the current file head or what the caller gets back, which an agent invoking a restore operation would reasonably want.

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?

There is a single parameter with 100% schema description coverage, including the UUID format and how to obtain it via list_files. The description adds nothing beyond the schema, which is the expected baseline when the schema fully documents the parameter.

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 gives a specific verb (restore) and resource (a previous version of a file) scoped to the user's Fulcra account, so the agent knows exactly what operation is performed. It does not explicitly distinguish itself from the similarly named sibling restore_data_type, though the file-vs-data-type noun difference makes the split reasonably inferable.

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 offers no when-to-use guidance, no prerequisites, and no named alternative. The useful routing hint ('version_id found via list_files with include_versions=true') lives only in the schema, not in the description text.

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=true, destructiveHint=false, and openWorldHint=false. The description adds some useful behavioral context with "without reading messages," but it does not explain query behavior, result contents, or how this search differs from opening contacts directly.

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?

It is a single front-loaded sentence with no filler, and the key verb appears immediately. The phrasing is somewhat cryptic, but it is structurally concise.

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 one-parameter search tool with no output schema and no schema descriptions, the description should clarify the query semantics and expected return shape. It only hints at behavior ("without reading messages") and leaves the central search semantics unexplained.

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 tool has one required parameter, "query," but schema description coverage is 0%. The description does not specify what the query matches against (contact names, identifiers, opening actions, etc.) or what format it expects, so the schema gap is not compensated.

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 has a verb ("Find") and a resource ("Agent Contact opening actions"), so it is more than a tautology. However, "opening actions for the composer" is undefined and the description does not distinguish this from siblings like open_agent_contacts or open_agent_contacts_home.

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?

There is no explicit guidance on when to use this tool instead of open_agent_contacts, open_agent_contacts_home, or other contact/message tools. Usage is only implied by the phrase "for the composer."

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?

The description adds substantial behavior beyond the annotations: delivery is not confirmed by status=posted, only own-channel readback is; retries must be bounded and reuse the same mid and payload; denial must never be bypassed; replies/acks target messages/replies, not acks; and a posted message/reply removes the entire saved contact status. These are important mutation, retry, and side-effect details for a destructive non-idempotent tool.

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 front-loads the core action before behavioral caveats. Some sentences are dense and jargon-heavy, such as the status=posted readback sentence, but there is little wasted text.

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 12-parameter mutation tool with an output schema, the description covers the important behavioral risks: partial delivery semantics, bounded retry rules, denial handling, reply/ack targeting, and the contact-status side effect. It is not fully complete because it does not clarify sibling selection against send_agent_message, but the key operational details are present.

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 the schema already carries most parameter meaning. The description still adds useful semantics for retry behavior via the same mid and payload, and clarifies that replies/acks target messages/replies rather than acks, which goes beyond the schema text.

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 action and target: 'Post to an existing exact-audience Event channel.' That is more precise than a tautology, but it does not clearly distinguish this tool from the sibling send_agent_message or explain what makes the 'contact' variant different.

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 some situational constraints, such as posting only to an existing exact-audience Event channel and not bypassing denial on retries. However, it does not explicitly say when to use this instead of send_agent_message or other contact tools, so the agent must infer the selection rule.

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?

The description adds important behavioral details, including that posting confirms only the sender's readback and that denial should never be retried. However, it also states that a posted message/reply removes the entire saved contact status, which is a destructive-side-effect disclosure that contradicts the destructiveHint=false annotation.

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 short and front-loads the primary action. The sentences are terse and mostly meaningful, though some phrasing is compressed enough to be slightly ambiguous.

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 schema and output schema are rich, so the description need not explain parameters or return values. It does cover key delivery and side-effect caveats, but it fails to clarify the relationship to send_agent_contact_message and contains a side effect that conflicts with the annotations.

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 schema already documents all 12 parameters in detail. The description adds audience context but does not provide additional per-parameter semantics beyond what the schema provides, making the baseline 3 appropriate.

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 action and medium: sending a message over a connect-our-agents connection. It specifies the audience as everyone in that connection. However, it does not explicitly distinguish this tool from the sibling send_agent_contact_message.

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 is implied by 'connect-our-agents connection' and the note that everyone in it can read the message. The warnings about retrying denial and readback status provide operational guidance, but there is no explicit statement of when to choose this tool over send_agent_contact_message.

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 destructiveHint=true and idempotentHint=true, but the description adds meaningful context: only the description marker changes, the change is verified by readback, and the label is untrusted display text rather than routing identity. This goes beyond what the annotations convey.

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, front-loaded with the action and scope, followed by the prerequisite and trust caveat. Every sentence carries information, though the semicolon structure is slightly dense.

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 two-parameter setter with no output schema, the description covers what is changed, the prerequisite, and the trust semantics of the label. It is nearly complete, though it could say more about overwrite behavior or error cases.

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 schema already documents both parameters fully. The description reinforces ownership and the trusted-display nature of the identifier but adds no syntax or format detail beyond the schema.

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 uses a specific verb and resource: "Label your own Event channel or legacy outbox", making it clear this sets a display label on an owned catalog entry. It does not explicitly differentiate itself from siblings like set_contact_status or update_data_type, but the object and effect are unambiguous.

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 a prerequisite ("Requires an unambiguous owned catalog entry") and scope ("your own Event channel or legacy outbox"), which implies when to use it. However, it offers no explicit when-not conditions or named alternatives, leaving the agent to infer boundaries.

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 destructiveHint=true and readOnlyHint=false, so the description adds real value by explaining that this is a full replacement (not a merge) and that passing {} reverts to global values — critical for a destructive override. The privacy note ('Stored privately, never on the connection') and the scope disclaimer about messages/sharing/checkpoints/scheduler further bound the blast radius, though the last clause is a bit ambiguous.

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 core semantics are front-loaded in the first clause, but the second line reads as a disjointed fragment ('No messages, sharing, checkpoints or scheduler edits') whose meaning is unclear without more context. It is compact with no padding, but the structure could be tighter.

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?

This is a destructive mutation with 4 parameters at 0% schema coverage, including an obscure expected_peer_userids safety parameter. An output schema exists, so return values needn't be explained, but the description omits what data_type and peer_userid mean and how expected_peer_userids guards concurrency — significant gaps for a destructive write.

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% across 4 parameters, including a nested 'overrides' object, so the description carries the full burden. It only explains the overrides parameter ({} restores globals); data_type, peer_userid, and especially expected_peer_userids (a concurrency/locking parameter) are left entirely undocumented.

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 and resource: 'Replace this contact's preference overrides', which clearly separates it from the read-only sibling get_contact_preferences. It does not explicitly name the sibling as an alternative, but the operation is unambiguous.

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?

'at the user's request' gives a light trigger condition, and '{} restores the global values' explains the reset case. However, there is no explicit guidance on when to call this versus get_contact_preferences or how it interacts with set_contact_status, leaving usage implied rather than stated.

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 the destructiveHint=true and idempotentHint=false annotations, the description discloses useful behavioral constraints: the status is peer-visible, writes require complete scoped reads, failures must not block other work, and denials must not be retried. It does not contradict 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 very compact and front-loads the core action and precondition. Some phrasing is dense and slightly cryptic, but there is little wasted text.

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 rich schema descriptions, an output schema, and annotations covering safety, the description supplies the key operational preconditions and failure-handling rules. It is largely complete, though it could better distinguish sibling tools and explain the status lifecycle.

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 all four parameters are already documented in the schema. The description adds conceptual context like shared facts and acknowledgements, but it does not add syntax or field-level meaning beyond the schema.

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 write action, 'Save a peer-visible Status pill,' and scopes it to the user's own Event connection. It is clearer than the title alone, but it does not explicitly distinguish this from related contact/status tools such as set_contact_identifier or set_contact_preferences.

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 explicit preconditions: share_contact_status must be enabled and scoped reads must be complete. It also gives when-not guidance such as never clearing on incomplete history and never retrying denial, though it does not name alternative sibling tools.

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?

The annotations already state that this is not read-only, not destructive, and closed-world. The description adds little beyond that: it does not explain that this likely initiates an upload session, whether follow-up chunk calls are required, or what the caller should do next.

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 front-loaded sentence with little waste. However, the trailing "from the file manager panel" is vague and does not meaningfully improve the definition.

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?

Although an output schema exists and annotations cover safety, the description omits the upload workflow relationship with upload_file_chunk. For an initiation tool in a file upload family, that context is important 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 100%, so path, size, and content_type are already documented sufficiently in the schema. The description adds no additional parameter meaning, which is acceptable given full schema coverage.

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 gives a specific verb and resource: it starts an upload. It does not distinguish this tool from the closely related upload_file_chunk sibling, and the phrase "from the file manager panel" adds UI context rather than clarifying the tool's role.

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?

There is no guidance on when to use this tool versus upload_file_chunk, write_file, or other file-related siblings. It also does not mention prerequisites or the upload workflow.

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?

Adds substantial behavior beyond the annotations: descriptions are shared with existing readers, expected_description is a stale-read guard rather than an atomic compare-and-swap, only verified=true confirms readback, and blind retries are forbidden. Annotations cover the safety profile (destructive=true, idempotent=false) and the description layers the operational consequences on top.

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?

Front-loaded with the mutation scope, then the safety caveats, with no filler sentences. The phrasing is telegraphic in places ('Legacy annotations are not supported') which costs a little clarity, but nothing is padding.

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 destructive mutation with an output schema, it covers everything an agent needs: authorization, field-replacement behavior, stale-read guarding, readback verification, and retry policy. Return-value detail is correctly left to the output schema.

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 the baseline is 3, but the description adds real meaning: 'Preserve unrelated description content' signals that description is a full replacement where partial edits destroy data, and 'expected_description rejects stale reads, not an atomic compare-and-swap' clarifies the concurrency guard's exact semantics.

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 precise verb and resource ('Update only name/description of an owned active Event/Metric type') along with the constraints (owned, active). The explicit exclusion 'No schema, record, or share changes' separates it cleanly from create_data_type, archive_data_type, restore_data_type and record_data without needing to name them.

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?

Gives clear operating context: user authorization required, read via get_data_catalog first, and reconcile rather than retry on uncertain writes. It does not explicitly contrast with sibling tools such as create_data_type or archive_data_type, so it stops short of full when/when-not routing.

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 disclose destructiveHint=true, but the description does not explain what may be overwritten, whether changes are reversible, or what permissions are needed. The exclusion sentence adds useful scope boundaries, but for a destructive settings update the description should say more about the destructive behavior beyond the annotation.

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 two short sentences with no wasted wording, and the main purpose is front-loaded before the exclusions. It is appropriately sized for the available text, though the content itself is sparse.

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?

This is a destructive mutation tool with a nested object parameter and no schema field descriptions, and the description does not sufficiently explain the `set` payload or destructive implications. The output schema means return values need not be explained, but key invocation and safety context is still 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 0% for a single nested `set` object with additionalProperties=true, so the schema itself provides little semantic guidance. The description mentions only checking_preferences text and does not explain the structure, required keys, or other accepted fields in `set`, leaving the parameter underspecified.

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 verb and resource: saving global contact preferences, including checking_preferences text. It does not explicitly distinguish this tool from sibling tools such as set_contact_preferences or get_contact_preferences, but the scope is still clear enough to identify the operation.

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 line "No messages, checkpoint changes or scheduler edits" gives useful negative guidance about what this tool is not for. However, it does not say when to choose this tool over alternatives like set_contact_preferences or get_fulcra_settings, so usage guidance remains implied rather than explicit.

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 state readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds little beyond 'from the file manager panel', which is irrelevant to an agent, and omits ordering, idempotency/retry, whether re-sending an offset overwrites data, and any size constraints.

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?

A single short sentence with no padding, so it is concise, but the length comes at the cost of under-specification rather than efficiency. The useful part (chunk of an upload) 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?

An output schema exists and the input schema is fully documented, so the basics are covered. However, a chunked-upload step tool is incomplete without sequencing and finalization guidance, which the description entirely omits.

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 each of upload_id, offset, and data is already documented in the schema. The description adds no extra meaning to any of the three parameters, which is the expected baseline when the schema does the work.

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 verb+resource combo ('Sends one chunk of an upload') is specific about the action, but it never explains the chunked-upload protocol it belongs to or how it relates to start_file_upload. An agent knows it moves bytes but not the larger workflow it participates in.

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?

There is no when-to-use guidance at all: not when to start chunking, how many times to call, whether chunks must be sequential, or what to call to finalize the upload. The only hint is the schema's note that upload_id comes from start_file_upload.

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?

Goes well beyond the annotations by disclosing non-obvious behavior: overwriting a path keeps prior versions (consistent with destructiveHint=false) and is reversible via restore_file, and writes are observable by other agents through get_data_updates under "file_changes". That side-effect visibility is exactly the kind of trait an agent cannot infer from structured fields.

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?

Front-loads the core action in one sentence, then adds versioning and cross-agent visibility in tight follow-ups. Slightly prose-heavy line wrapping but every sentence carries distinct information.

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 4-param, fully documented, non-output tool with annotations present, this covers the semantics an agent needs to call it correctly. Only minor gaps, such as permission/auth requirements or path conventions, are left implicit.

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%, with path format, the 5 MB base64 cap, the upload_link flow, and MIME-type guessing all documented inline. The description adds nothing about parameters, so the 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 and resource ("Write a file to the user's Fulcra account") and immediately qualifies the write semantics (new version on existing path). It is clearly separable from read_file, list_files, delete_file, and the chunked upload tools without opening any schema.

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?

Gives concrete context for when files are the right mechanism ("files are a good way to pass data between agents") and points to restore_file for recovering earlier versions. It does not explicitly route away from start_file_upload/upload_file_chunk in the description itself — that routing lives only in the content param's schema text.

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