Fulcra MCP Server

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

Annotations declare readOnlyHint=true, and the description confirms this is a read/list operation. It adds the useful fact that results are bare UUIDs rather than the IDs get_records expects, which is real behavioral context. It doesn't describe return shape, but an output schema exists so that burden is lifted.

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 deprecation notice followed by the alternative and the contrast. Slightly wordy in the second sentence but every clause carries meaning, 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 zero-parameter deprecated list tool with an output schema, the description supplies the two things an agent actually needs: the replacement tool and the ID-format caveat. 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?

Zero parameters, so the baseline is 4. The description appropriately focuses on output semantics (bare UUIDs vs. get_records IDs) rather than parameter detail.

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 what the tool lists (older annotation types) and explicitly contrasts it with the replacement by scope (only older annotation types, bare UUIDs). The deprecated framing makes the resource clear. It stops short of a crisp standalone definition but is distinguishable from get_data_catalog.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes the agent to get_data_catalog(category="user_defined") as the replacement and states why (that lists every user-defined type including Event/Metric, with the IDs get_records takes). The when-to-use alternative is named unambiguously.

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 declare destructiveHint=true, so the safety profile is already flagged; the description usefully refines it by clarifying this is a soft-delete whose data remains recoverable via restore_data_type, which materially changes how an agent should weigh the operation. It does not, however, mention any auth requirements or side effects on dependent records beyond 'its recorded 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?

Three short sentences, front-loaded with the core action, then recovery, then eligibility. Every sentence carries distinct information with no repetition of the title or schema.

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 tool with an output schema and destructiveHint annotations, the description supplies everything else an agent needs: the soft-delete semantics, the restore path, and the type-eligibility constraint. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter's format ('<BaseType>/<uuid>' from get_data_catalog) is already documented in the schema. The description adds no parameter-level meaning, 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.' The parenthetical disambiguates the operation from hard deletes like delete_file, and the scope ('user-defined') separates it from other data-type operations.

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 names the counterpart restore_data_type as the recovery path and states the eligibility precondition ('Only user-defined types (created via create_data_type or the Context app) can be archived'). An agent knows both when this applies and when it does not.

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 only supply destructiveHint=false, so the description carries most of the behavioral load: it discloses reversibility via archive_data_type and the structural constraint that older bases reject custom fields. It does not cover name-uniqueness behavior, permission requirements, or side effects on existing records, 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, front-loaded paragraphs: purpose, base_type choice, then tool workflow. No filler sentences; each line either routes the agent or prevents a misuse (e.g., fields on legacy bases).

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 the description covers the surrounding workflow and reversibility. Missing only edge-case behavior (duplicate names, tags auto-creation semantics on legacy bases) for a mutation tool with sparse 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 coverage is 100%, so 3 is the floor, but the description goes beyond the schema by explaining the base_type lifecycle tradeoff (new vs. legacy bases and which accept `fields`), which is decision-relevant guidance the per-parameter descriptions don't frame. It does not add syntax detail beyond the schema, so it stops short of 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 opening sentence states a specific verb and resource ('Create a user-defined data type') plus the intent ('so the user can track something new'). It cleanly separates itself from record_data (writing values), get_data_catalog (reading metadata), and archive_data_type (removal).

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 routing: prefer base_type 'event' or 'metric' for new tracking, with the older annotation bases named and characterized ('take no fields'). It also names the follow-on and reversal tools (record_data, get_data_catalog, get_records, archive_data_type), so the agent knows the full workflow around this call.

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 only declare destructiveHint=false, so the description carries most of the burden and delivers: sharing configured via `data_types` 'cannot be changed later', creating does not make the user a member, and the group ID is secret-like because anyone who learns it can join and the owner cannot remove members. That is security- and irreversibility-relevant behavior an agent needs before invoking.

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 purpose, then consequence of each mode. Six sentences for a tool with security implications is defensible, though the second paragraph is dense and could be tightened slightly without losing content.

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. The description covers the two operating modes, the membership gap requiring join_group, immutability, and the security caveat — everything an agent needs to call and sequence this 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 the baseline is 3, but the description adds genuine semantics: `data_types` triggers per-member read-only sharing bounded by the time range and is immutable afterward, and omitting it produces a group that 'collects nothing'. This goes beyond the schema's terse 'Data type IDs members will share'.

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 ('Create a group of Fulcra users') plus the motivating use case (sharing with several people at once), which distinguishes it from create_share and join_group in the sibling list. An agent can pick this tool 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 branches on the `data_types` parameter (omit → inert target for create_share; include → irrevocable read-only sharing), and names the follow-up action (`join_group`) required for shares to reach members. It even gives a when-not constraint: 'Only create a group the user asked for.'

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 only declare destructiveHint=false, so the description carries most of the burden and does so well: it discloses the read-only nature ('they can never write here'), the coordination workflow, and a safety caveat about scope. It does not cover revocation, expiry, or what happens on re-share of an existing label.

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 sentences, front-loaded with the core action and scope. The agent-to-agent paragraph is longer but earns its place as non-obvious usage context; nothing is redundant with the schema.

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 present and 100% schema coverage across nine params, the description need not explain return values or argument formats. It supplies the one thing structured fields cannot: the read-only sharing semantics and recipient access model. Revocation/lifecycle behavior remains unstated but is largely a delete_share concern.

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 with types, formats, and mutual exclusions. The description's only added semantic is that recipients read via this user's fulcra_userid, which does not map tightly onto the with_user_ids parameter. 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 ('Share files or data types from this account with other Fulcra users') plus the read-only scope, which distinguishes it from siblings like write_file, delete_share, and list_shares. An agent can identify the operation 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?

Gives clear context: recipients read by passing this user's fulcra_userid, the agent-to-agent folder-sharing pattern is spelled out, and it warns 'Only share what the user asked to share.' It does not name alternative tools or when NOT to use this one, 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?

With readOnlyHint=true already covering the safety profile, the description usefully scopes the behavior: it reads the *local* session's stored credentials, not arbitrary tokens, and reveals only expiry and refresh-token *presence* rather than token contents. That last point is a meaningful disclosure an agent could not infer from the schema or 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?

Three short sentences, front-loaded with the core behavior and followed by scope and use case. The opening sentence is slightly generic ("Return info about...") and partly restated by the second, but there is no real 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?

An argument-less, read-only diagnostic tool with an output schema needs no further explanation: what it reads, where it reads from, and when to use it are all covered. Nothing an agent needs to invoke it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 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?

The description states a specific verb and resource: it returns expiry and refresh-token presence for the local stdio session's stored Fulcra credentials. That is precise enough to distinguish it from data-fetching siblings like get_user_info or get_data_catalog. It does not explicitly contrast itself with the nearest sibling, 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?

"Useful for diagnosing authentication issues" gives an explicit situational trigger for reaching for this tool. It does not name an alternative or state exclusions, but the context is clear and unlikely to be confused with any other sibling.

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 only say destructiveHint=true; the description adds the materially important fact that this is a SOFT delete where earlier versions are retained and recoverable, plus the exact mechanism to recover them. This substantially changes the agent's risk calculus beyond what the annotation conveys.

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, no waste, and the operation is stated before the recovery nuance. Every element 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?

An output schema exists, so return values need no explanation. For a one-parameter mutation, the description covers what is deleted, that it is reversible, and how to reverse it — nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and schema description coverage is 100% ('The full path of the file to delete'). The description adds no syntax, format, or path-resolution detail beyond the schema, 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 ('Delete a file stored in the user's Fulcra account') and implicitly scopes it as file-specific. It distinguishes itself from the sibling restore_file by framing them as a complementary pair rather than competing operations.

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?

Clearly conveys the context of use and the recovery path, naming both `restore_file` and `list_files` with the required `include_versions=true` flag. It stops short of explicit when-not-to-use guidance (e.g., preferring archive over delete), but the operational routing is solid.

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?

destructiveHint=true already declares the safety profile, so the description adds real value beyond it: 'Permanently' signals irreversibility and 'removing all its members' discloses a side effect on other entities. It stops short of stating recovery options or permission-failure 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?

One sentence, zero filler, with the permanent/deleting action front-loaded and the cascade consequence attached. Nothing to trim.

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 destructive tool with an output schema and destructiveHint annotation, the description covers the essentials: ownership precondition, irreversibility, and member cascade. Only edge-case behavior (shared resources, failure modes) 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?

Single parameter with 100% schema coverage; the schema already explains that group_id comes from get_groups. The description adds no format or sourcing detail beyond the schema, so 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 (permanently delete), resource (group), an ownership precondition, and the cascade effect on members. An agent can distinguish this from leave_group or delete_share 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?

The ownership condition ('a group the user owns') implies when this is valid, but the description never states when to choose it over leave_group or what happens if ownership is absent. Usage is inferable 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 declare destructiveHint=true, so the mutation profile is already covered; the description still earns credit by naming exactly what is destroyed — all recipients' access is revoked. It does not say whether the deletion is permanent/irreversible or what happens to recipients' local copies, so it stops short of full disclosure.

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 sentence with zero filler, front-loading the outcome ("Stop sharing") before the mechanism. Every clause carries 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?

With an output schema present and destructiveHint covering safety, the description needs only to convey scope and effect, which it does. Minor gaps remain around irreversibility and any permission requirements, but nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the share_id parameter is documented with the exact source call list_shares(direction="outgoing"). The description adds only the ownership qualifier ("this user created"), which is marginal beyond what the schema already provides, 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 ("delete a share") plus the effect ("Stop sharing ... revoking all recipients' access") and an ownership scope ("this user created"). An agent can distinguish this from delete_file, delete_group, and create_share 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?

The phrase "a share this user created" implies a precondition (you can only remove your own shares), which is useful context for choosing this tool. However, it never states when to use this versus alternatives like create_share or list_shares, nor any exclusions or prerequisites beyond that implied ownership constraint.

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 a safe read (readOnlyHint=true). The description goes beyond that by disclosing the partial-overlap inclusion rule, the participant_count field, that include_participants is required to get invitees and responses, and that returned timestamps carry time zones. Pagination and result-size limits are still unmentioned, 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?

Four short sentences, no padding, and the core scope statement comes first. The participant and time-zone guidance are earned additions rather than restatements, though the sentence on time zones is slightly advisory rather than instructional.

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 present and full schema description coverage, the description only needs to add semantics — and it does: range inclusion, the participants opt-in, and time-zone awareness. Only pagination/nonexistent-results behavior is arguably left 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?

Schema description coverage is 100%, so all five parameters are already documented, including the inclusive/exclusive boundary on start_time and end_time. The description adds the 'why' for include_participants but nothing new about calendars or fulcra_userid, 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 and resource ('Retrieve the user's calendar events') and pins the scope with 'within a time range', then clarifies the inclusion rule ('occur at least partially during the range'). That distinguishes it from get_calendars, which enumerates calendars rather than events, though the description never names that sibling explicitly.

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 operational guidance on the include_participants flag ('pass ... when you need who was invited and their responses') and on timestamp handling, which is genuinely useful. However, it offers no when-to-use/when-not guidance relative to alternatives such as get_calendars or get_records, so routing among siblings is left 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful context that results are grouped by account/source, but does not mention auth requirements or the cross-user sharing behavior implied by fulcra_userid. Adequate but not rich 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?

Two short sentences with zero filler; the primary purpose is front-loaded and the workflow hint follows. Every sentence 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?

An output schema exists, so return values needn't be explained, and the description covers purpose plus the key sibling relationship. The only gap is not surfacing the optional cross-user listing use case in prose, though the schema covers it.

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 optional fulcra_userid parameter is fully documented in the schema, including its cross-user sharing semantics. The description adds no parameter meaning beyond that, so the baseline 3 is correct.

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 ('List the user's calendars') and adds scope detail ('grouped by account/source') that differentiates it from the sibling get_calendar_events, which is named explicitly. An agent can tell what this returns 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?

Provides a concrete downstream workflow: use the names or IDs with get_calendar_events to filter by calendar, which names the sibling and the reason to call this first. It does not give explicit when-not conditions (e.g., when to skip this and query events directly), 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 readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: what the return groups contain, and the ownership rule that a shared type carries the other user's fulcra_userid which must be passed to read their data. It stops short of describing default unfiltered behavior or result size, so it is strong but not exhaustive.

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 purpose, then the prerequisite, then the cross-user caveat — no filler sentences. Slightly dense in the first paragraph's enumeration, but every clause carries operational meaning.

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 present, return-value detail is unnecessary, and the description covers the remaining agent needs: what the catalog contains, when to call it relative to data-fetching tools, and how to handle types shared by other users.

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 filters are already documented with examples and defaults. The description reinforces fulcra_userid's shared-type semantics but adds little the schema does not already state; 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 ('Get all data types available for this user') and adds scope detail — grouped by MCP tool, and enumerating the included categories (location, events, user-defined types, annotations, measurements). An agent can distinguish this catalog enumeration from siblings like get_records, get_time_series, and get_data_updates.

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 sequencing ('Call this before requesting time-series data or raw records'), a usage constraint ('only use a data type with the tools named in its group'), and cross-user guidance explaining when fulcra_userid applies. This is genuine when/when-not guidance rather than implied context.

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?

readOnlyHint=true already signals this is a safe read, so the bar is lower, and the description still adds genuinely useful behavior: the time range filters on ingestion/sync time, not record timestamps, with a concrete example ('last night's sleep records typically arrive this morning'). That non-obvious semantic would be easy to misuse without it. It says nothing about result size, pagination, or cost, so it stops 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 sentences, front-loaded with the core purpose, then the crucial time-semantics caveat, then the follow-up instruction. No filler, no restatement of the name or title, and the most misuse-prone fact is surfaced prominently.

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-value detail is correctly omitted. For a read-only, four-parameter summary tool with full schema coverage, the description supplies everything an agent needs: scope, the timing gotcha that determines correct arguments, and what to do with 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 coverage is 100% (baseline 3), and the description goes beyond the schema by defining what start_time/end_time actually filter on — processing/sync time rather than record time. This is meaningful added semantics for the two required parameters, though the optional fulcra_userid and include_shared parameters are explained only in 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 and resource ('Summarize the data that arrived in the user's account during a period of time') and immediately scopes it as a discovery/changefeed tool rather than a data reader. The closing clause routes the agent to other tools for the actual changed types, so an agent can distinguish it from get_records, get_sleep, or get_time_series 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 an explicit trigger ('find out what new data exists since a previous check') plus the required follow-up workflow ('then query the changed types with the appropriate tools'). It lacks explicit when-not guidance and does not name the alternative tools, leaving the agent to infer which ones qualify as 'appropriate'.

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 only declare readOnlyHint=true. The description adds useful behavior beyond that: list mode omits long-form fields, private groups are visible only with subscribed_only, and group_id returns the complete record. It does not discuss auth requirements, rate limits, or pagination, but those are less critical for a read-only tool with an 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?

Three sentences, front-loaded with the core action. The group definition and create_share pointer support correct usage, and the final sentence concisely explains the two invocation modes. 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 two optional parameters, 100% schema coverage, and an output schema, the description supplies the needed context: what the tool does, the two modes, the privacy behavior of subscribed_only, and the cross-tool share workflow. 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 schema already documents both parameters and the baseline is 3. The description adds nuance by clarifying that private groups the user joined appear only when subscribed_only is set, and that group_id returns one group's complete record. These details go slightly beyond the schema's wording.

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: 'List Fulcra groups, or get one group's full details.' It also explains the group concept and points to create_share for sharing, which helps differentiate from share-related siblings, but it does not explicitly name list_shares or state when to choose this over other group tools.

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?

Describes when to pass group_id (for one group's complete record) and when to set subscribed_only (private joined groups appear only then). It also mentions create_share as the alternative for sharing with all group members. However, it does not state any when-not conditions or exclusions for other listing 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds valuable behavior: fallback to closest sample within window_size, and the need to translate timestamps to local time zone. It does not mention pagination or data staleness. With annotations covering safety, this is strong added context.

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 focused sentences: purpose, fallback behavior, and time zone guidance. It is front-loaded and no sentence is wasted, though it could be slightly 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?

For a read-only tool with an output schema and full schema coverage, the description provides the key behavioral nuance (closest sample within window) and an important operational note about time zones. It is complete enough for an agent 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 description coverage is 100%, so all parameters are documented in the schema. The description reiterates the window behavior but adds no syntax or format details beyond what the schema provides. 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?

The description clearly states a specific verb and resource: 'Gets the user's location at the given time.' This distinguishes it from sibling tools like get_location_time_series (which retrieves a series) and get_records (generic records). It does not explicitly name siblings, 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?

The description explains that if no sample exists for the exact time, it searches within a window, clarifying the tool's temporal tolerance. This is useful context for choosing between this tool and get_location_time_series. However, there is no explicit 'use this instead of X when Y' 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?

The readOnlyHint annotation already establishes this as a safe read. The description adds genuinely useful context that result timestamps carry time zones and should be translated to the user's local tz. It does not, however, mention sampling behavior, result volume, or limits, so it adds value without being rich.

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 with no waste; the resource description is front-loaded and the timezone note earns its place by changing how the agent should present results.

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 cover the safety profile. Combined with the timezone guidance, the definition is nearly complete; the only gap is routing guidance relative to the location/time-series siblings.

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 (start/end time, sample_rate, change_meters, reverse_geocode) are already documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the heavy lifting.

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: 'Retrieve a time series of locations that the user was at.' An agent can distinguish this from the single-point sibling get_location_at_time by the 'time series' scope. It stops short of naming any sibling explicitly, 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?

Usage is implied by the resource described (fetch historical location samples over a range), but there is no explicit when-to-use, when-not-to-use, or named alternative against get_location_at_time or get_time_series. The agent must infer the routing itself.

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 this is a safe read (readOnlyHint=true), so the bar is lower, yet the description adds real behavioral context: results are raw samples that may come from multiple sources and can overlap, range-intersection semantics, automatic endpoint selection, and that returned timestamps include time zones. It omits pagination/volume limits, so it stops just 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?

Front-loads the core action in the first sentence, then adds scoping and routing detail. Every sentence earns its place, though it is denser than strictly necessary and could be tightened slightly.

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 format need not be explained, and the description still covers the remaining gaps an agent needs: data_type sourcing, time-range semantics, the get_time_series alternative, and timezone translation. Nothing essential for correct invocation 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 meaning beyond the schema: the '<BaseType>/<uuid>' format for data_type IDs and the rule that records overlapping the window are included. It says little extra about fulcra_userid, keeping it from 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 (Retrieve) plus resource (the raw records of any data type) and scope (during a time period). It explicitly distinguishes itself from the sibling get_time_series by contrasting raw samples with calculated per-interval values, so an agent can separate the two without opening either 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 names the alternative (get_time_series) and the condition that selects it (calculated per-interval values of numeric data types). It also routes the agent to get_data_catalog for discovering valid data_type IDs, giving clear when-to-use and where-to-find-input 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?

The readOnlyHint annotation only establishes safety; the description adds substantial behavioral context the annotation cannot: results grow with detail level, sleep sessions cross midnight, stage integers decode to specific sleep states, and returned timestamps carry time zones that should be translated to the user's local zone. This is exactly the added value a description should provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The level-selection rule is front-loaded, the three modes are a tight bulleted list, and the trailing caveats about midnight-spanning ranges, stage integers and time zones are each a single clause. 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 13 parameters and an output schema present, the description supplies the pieces the schema cannot: level-selection heuristics, the midnight boundary caveat, and the stage-code legend. Return values need not be described since an output schema exists, and the remaining params are documented in the 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 goes beyond the schema by defining the stage integer encoding (0=In Bed ... 5=REM) and by explaining the semantics of the level options, which the schema only gestures at with "see above". It does not clarify the more obscure params (cycle_gap, gap_stages, merge_*), keeping it from 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?

"Return the user's sleep data at a chosen level of detail" is a specific verb+resource, and the three level options (aggregate/cycles/stages) carve out a clear domain distinct from siblings like get_workouts, get_records, and get_time_series. An agent can tell what this returns and at what granularity 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 real routing guidance ("Pick the coarsest level that answers the question") plus concrete best-for examples such as multi-day vs single-night questions, and it warns that sleep spans midnight so the range must be extended. It stops short of naming when to prefer a sibling tool (e.g. get_time_series) for non-sleep data, so no explicit exclusion criteria.

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 `readOnlyHint: true` already covering the safety profile, the description adds useful operational context: result timestamps include time zones and the agent should translate them to the user's local time zone when known. It also discloses the data-type eligibility constraint. It does not discuss pagination or response shape, but an output schema exists.

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 with no filler. It front-loads the core action, then the eligibility and alternative tool, then the time-zone handling note.

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 query tool with full parameter descriptions and an output schema, the description covers the critical non-schema context: supported data types, the fallback to `get_records`, and time-zone handling. Nothing essential for correct invocation appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all seven parameters, including defaults, accepted calculation names, and time-zone requirements. The description only reinforces that `data_type` comes from `get_data_catalog` and that timestamps carry time zones; it adds little parameter 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 uses a specific verb and resource: "Get calculated per-interval time-series values for a single data type." It distinguishes this tool from the sibling `get_records` by explaining which data types are supported and where unsupported types should be read instead.

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 states the eligibility condition: only data types that `get_data_catalog` lists as usable with this tool are supported, and other types can be read with `get_records`. This gives clear when-not and alternative guidance, though it does not compare against other series-specific siblings such as `get_location_time_series` or `get_sleep`.

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, so the safety profile is covered without the description's help. The description adds modest value by naming the kind of metadata returned, but says nothing about freshness, auth/scope requirements, or error behavior. With annotations carrying the safety burden, this is adequate but not rich.

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 core purpose. The second sentence partially repeats the first ("general info" vs "user references"), which is mild redundancy, but the total length is appropriate for a simple tool.

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 no-parameter read tool with an output schema and readOnlyHint annotation, the description supplies everything an agent needs to select and call it. Return-value detail is legitimately delegated to the output schema, so the remaining gap is minor.

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 no parameters, so per the rubric the baseline is 4. The description correctly implies there are no inputs to specify, and nothing about the empty schema is left ambiguous.

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 general info about the Fulcra user") and enumerates representative return fields (time zone, calendar ids, metadata). It is clear enough to distinguish from data-oriented siblings like get_records or get_calendars, though it does not explicitly name a sibling the way the strongest definitions do.

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 zero-parameter, read-only nature of the tool, so an agent can infer it is a cheap 'who am I / what context am I in' call. However, there is no explicit when-to-use guidance and no mention of when another sibling (e.g. get_calendars, debug_token_info) would be more appropriate.

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 readOnlyHint annotation already establishes this as a safe read, so the description's burden is lighter. It earns credit by disclosing a non-obvious behavioral trait beyond the structured fields: returned timestamps carry time zones and the agent should translate them to the user's local time zone.

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 with no filler, and the core purpose is front-loaded before the timestamp-translation note.

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-value explanation is not needed, and the required parameters plus the time-zone handling note cover the essentials. Slight gap: no mention of result volume, pagination, or which metrics a workout record contains.

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 start_time, end_time, and fulcra_userid each documented including the ISO8601-with-tz requirement. The description adds no parameter meaning beyond that, 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 (get), resource (workouts), and scope (during a period of time), which is clear enough to distinguish from unrelated siblings like get_sleep or list_files. It does not, however, explicitly contrast itself with the neighboring activity-data tools (get_records, get_time_series), so sibling differentiation is left to inference.

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 the use case (fetch workouts within a start/end window) but never states when to prefer this over get_time_series, get_records, or get_sleep, nor any prerequisites such as authentication or data-sharing requirements.

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 only declare destructiveHint=false, so the description carries the burden and delivers: joining may share the group's listed data types read-only until the user leaves, and anyone with the group ID can join. These side-effect and access-control disclosures are material and not found in 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 key constraint (explicit user request) is front-loaded, and subsequent sentences each add distinct, necessary information: sharing side effects, prerequisite to show details, and the open-join warning. 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?

An output schema exists, so return values need not be explained. The description covers the consent prerequisite, side effects, parameter source, and a security caveat, leaving no critical gap 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% and the single `group_id` parameter is already documented as coming from `get_groups`. The description reinforces this but adds no syntax or format detail beyond the schema, 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 ('Join a Fulcra group') and immediately distinguishes it from related siblings like `get_groups` (source of IDs) and `leave_group` (the inverse operation). An agent can identify the tool's role 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 requires the action be 'at their explicit request' and directs the agent to 'Show the user the group's details first,' making the consent and prerequisite conditions clear. It also names `get_groups` as the source for the required ID.

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 destructiveHint annotation already signals that this is a destructive operation. The description adds concrete behavioral consequences: stopping data-type sharing with the group owner and stopping receipt of shares made to the group. It does not discuss reversibility or permission requirements, but it meaningfully supplements 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?

Two tightly written sentences, front-loaded with the action and then the consequence. Every sentence earns its place with no redundancy 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 one-parameter destructive tool with an output schema and a destructiveHint annotation, the description covers the essential trigger and effect. It leaves out whether the action is reversible and what permissions or confirmation flow may apply, but those gaps are minor given the surrounding structured data.

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 well documented in the schema itself, including its source via get_groups(subscribed_only=true). The description adds no additional parameter meaning, so the baseline of 3 applies when the schema already 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 description states a precise verb and resource: 'Leave a Fulcra group on the user's behalf.' It clearly distinguishes the membership-exit action from sibling tools like delete_group and create_group, and adds scope that an agent can act on 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?

It gives an explicit usage condition: the action happens 'at their explicit request' and 'on the user's behalf.' That is clear context for when to call it. It does not, however, name alternatives or when-not-to-use conditions, 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 readOnlyHint=true, so the safety profile is covered by structured data. The description adds the sharing-visibility rule at a high level ('or files another user shares'), but omits pagination, result-size limits, and how path scoping behaves at the root — details the schema partially carries for fulcra_userid but not as behavioral context.

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 paragraphs, front-loaded with the core action and followed by useful workflow context. No filler, though the second paragraph describes a broader pattern rather than this tool specifically, which slightly dilutes focus.

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 present the description needn't explain return values, and all three parameters are schema-documented, so nothing essential to invocation is missing. Minor gaps remain around pagination and large-listing behavior, but the read-only annotation and full schema coverage make this largely 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 all three parameters (path, fulcra_userid, include_versions) are documented in the schema itself, including the include_versions/restore_file relationship. The description adds no syntax or format meaning beyond that, 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+resource with scope: 'List the files in the user's Fulcra account, or files another user shares.' The second paragraph names sibling tools (write_file, read_file, get_data_updates) and situates this tool in that workflow, which sharpens the distinction, though it never explicitly says when to prefer list_files over read_file.

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 explains the inter-agent file-passing pattern and mentions the related tools, which implies why an agent would list files. However, it gives no explicit when-to-use/when-not-to-use rule or alternative selection guidance (e.g., when to list vs. read directly, or how to discover shared paths).

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 readOnlyHint=true already covering safety, the description adds real behavioral context: the meaning of a `group_id` field, why the caller's own ID is returned, and the cross-tool handoff for reading another user's shares. It does not discuss pagination or result size, so not a full 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?

Front-loaded with the core purpose, then the parenthetical and group/ID notes in two further sentences. Each sentence carries information, though the final ID sentence is slightly incidental to the listing action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only listing tool with an output schema, the description supplies the interpretive context an agent needs: what incoming vs outgoing entries mean, how to decode group_id, and how to use the returned user ID. 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?

The single `direction` parameter is fully documented in the schema (100% coverage, enum of outgoing/incoming/both). The description's framing of two-way sharing aligns with the default 'both' but adds no new syntax or constraint beyond the schema, 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?

The first sentence gives a specific verb (List) and resource (shares) with an explicit two-way scope: what the user shares out and what others share with them. This clearly separates it from create_share, delete_share, and the group tools by describing the exact object it enumerates.

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 tells the agent how to act on results ('read it by passing their `sharing_fulcra_userid` as `fulcra_userid` to the file and data tools') and routes group-related entries to `get_groups`. It states clear context but stops short of explicit when-not/lookup-vs-write exclusion rules.

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, so the safety profile is covered. The description adds useful context that another user's shared files can be read, but does not disclose error handling, truncation behavior, or binary file handling beyond what the schema already provides.

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 that communicates the core action and access scope with zero waste. It is appropriately sized for a simple read 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 simple read tool with rich schema, annotations, and an output schema, the description covers the main access modes. It could mention edge cases like directory paths or missing files, but nothing critical is missing 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 coverage is 100%, and the description adds no parameter-specific meaning. The baseline of 3 is appropriate because the schema fully documents all four parameters, including path, max_bytes, fulcra_userid, and include_binary.

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 clear verb+resource: reading a file from the user's Fulcra account or a shared file from another user. It distinguishes itself from write_file/delete_file by the 'read' verb and shared access, but does not explicitly contrast with list_files or other 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?

No guidance on when to use this tool versus alternatives like list_files (for browsing) or get_records. It only states the access scope (own files or shared files), leaving the agent to infer appropriate contexts without explicit conditions 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 only declare destructiveHint=false, so the description carries most of the behavioral burden. It usefully discloses the user-defined ID form ('<BaseType>/<uuid>') and the read-back path, but says nothing about failure modes, whether re-recording overwrites, or permission requirements.

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 core action and then the prerequisite/read-back routing. Tight overall, with only mild redundancy in 'record a record'.

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 present, return values need not be explained, and the description covers the key prerequisite flow and ID conventions. It is nearly complete for a 7-parameter mutation tool, missing only edge-case behavior.

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 beyond it by explaining the '<BaseType>/<uuid>' ID form that the schema's data_type description omits, which is real added meaning for the required 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?

States a specific verb+resource ('Record a single record') and implicitly contrasts with the read-side sibling get_records mentioned later. The phrasing 'record a record for a recordable data type' is slightly circular, but an agent can still tell this is the write-side counterpart to 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?

Explicitly routes the agent: use get_data_catalog to find data types, create_data_type to make new ones, get_records to read data back. It gives clear context for the prerequisite lookup step, though it never states when NOT to use this tool.

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 only declare destructiveHint=false, leaving most of the behavioral burden on the description. It does not state permission requirements, idempotency, what happens if the type is not archived or the UUID is unknown, or whether restoring can conflict with an existing type.

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 zero waste; verb and resource come first. It is however terse to the point of omitting useful context, which keeps it short of a 5.

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 required parameter, an output schema present, and a safety annotation, an agent can invoke this correctly from the description. For a state-mutating restore operation the missing edge-case and permission context leaves it only minimally 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 coverage is 100% and the schema already documents the "<BaseType>/<uuid>" format of data_type. The description adds no format, constraint, or sourcing detail beyond the schema, so 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 ('Restore') and resource ('archived user-defined data type'), so the action is unambiguous. It does not name the counterpart sibling archive_data_type/create_data_type, so differentiation is left to inference.

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 when-to-use, when-not-to-use, or alternative guidance. The precondition ('archived') is embedded in the object phrase but the description never routes the agent between archive_data_type, create_data_type, and this tool.

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 only annotation is destructiveHint=false, and the description adds no behavioral context beyond that. It does not explain what happens to the current file version, whether the restore is reversible, what permissions are needed, or any 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?

A single front-loaded sentence with no wasted words. It states the action and resource immediately.

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 operation is simple, the parameter is fully documented, and an output schema exists, so return values need not be described. However, for a restore/mutation tool, the description omits timing, effect on the current version, and reversibility, leaving material gaps despite schema and annotation coverage.

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%; version_id is fully documented as a UUID found via list_files with include_versions=true. The description adds no parameter meaning beyond the schema, so the baseline score 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: 'Restore a previous version of a file.' The resource scope clearly separates it from read_file, write_file, delete_file, and list_files, though it does not explicitly name any sibling 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?

The description gives no when-to-use, when-not-to-use, or alternative-tool guidance. The schema notes where version_id comes from, but the description itself does not route the agent or state 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?

With only destructiveHint=false in annotations, the description carries most of the burden and does so well: it discloses that writing to an existing path creates a new version, that earlier versions are retained and restorable, and that changes are externally observable via get_data_updates. Permissions or size limits are not addressed, but the non-destructive versioning behavior is clearly consistent with 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?

Front-loaded with the core action in the first sentence, followed by two sentences of genuinely useful behavioral context. No filler or repetition.

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. The description covers versioning, recovery via restore_file, and cross-agent visibility, giving an agent enough to call it correctly; only auth/permission expectations are 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?

Schema coverage is 100%, so the baseline is 3, but the description adds path-specific meaning beyond the schema by explaining what happens when the path already exists (new version rather than overwrite). Parameter type/format details are still left to 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 and resource (write a text file) and the target scope (the user's Fulcra account). This plainly distinguishes it from siblings like read_file, list_files, and delete_file without needing to open 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 a clear when-to-use motivation (files as a way to pass data between agents) and routes to related siblings (restore_file, read_file, get_data_updates). It lacks an explicit when-not or a stated alternative for other write paths, 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.