Swarmail

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

Beyond the annotations (readOnly, idempotent and destructive all false), the description discloses non-obvious behavior: repeated calls preserve the first read/acknowledge timestamps but refresh the agent's activity time, the sender sees the acknowledgement in get_message_delivery_receipt, ack_overdue_only stops listing it, and it fails with NOT_FOUND unless the caller is a recipient. That is far more than the structured fields 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?

It is dense but every sentence earns its place: purpose and returns first, then repeated-call semantics, then when-to-use, then downstream effects, then the sibling alternative and failure mode. No filler or restatement of the name.

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 compensates by naming the returned fields (message_id, acknowledged, acknowledged_at, read_at). It also covers prerequisites, side effects on other tools, and the failure condition, so 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 description coverage is 100%, so all three parameters are already documented in the schema, and the description adds no format or constraint detail beyond implying recipient status (which relates to the NOT_FOUND failure). Baseline 3 applies when the schema carries the parameter burden.

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 names a specific verb and resource ('Acknowledge one received message and mark it read') and even enumerates the returned fields. It is cleanly distinguished from its nearest sibling by the explicit routing sentence 'To mark read without acknowledging, use mark_message_read.'

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 states exactly when to use it ('Acknowledge ack_required mail after acting on it'), what to do otherwise ('if you cannot or will not act, reply with the reason'), and names the alternative tool (mark_message_read) for the read-only case. Nothing 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 idempotentHint=true, readOnlyHint=false and destructiveHint=false; the description goes further by explaining the mechanism behind idempotency (same repository path returns the existing project), the fields returned (id, slug, human_key, created_at), and the NOT_FOUND failure mode of dependent tools. Only auth/permission requirements are unaddressed, which is a minor gap for a local project-registration 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?

Three compact sentences, each carrying distinct information (scope, idempotency rule, dependency/alternatives), with the primary action front-loaded. Nothing is redundant 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?

With no output schema, the description compensates by naming the returned fields, and it covers the state-dependency and idempotency behavior an agent needs before calling. There is no meaningful gap for a one-parameter, non-destructive 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?

With a single parameter and 100% schema description coverage, the baseline is 3, but the description adds meaning beyond the schema by tying human_key to project identity semantics: repeating the same repository path returns the existing project rather than creating a duplicate. It stops short of restating the absolute-path formatting constraint already documented 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?

The description states a specific verb and resource ('Create a project without registering an agent') and immediately distinguishes itself from the two siblings that also create projects, register_agent and macro_start_session. An agent can tell exactly what this tool is and is not 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 explains when to reach for this tool (you want a project without registering an agent), when the call is redundant (register_agent and macro_start_session create it themselves), and the prerequisite consequence of skipping it (other tools fail with NOT_FOUND). That is explicit when/when-not/alternative 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 (readOnlyHint=false, destructiveHint=false) are consistent with the description, which adds real side-effect context: mark_read defaults to true, so it flips read state, and 'include_bodies adds body_md' / 'mark_read:false' for preview. It also gives the pagination termination rule ('Stop when fewer than limit messages return') and the filter-combination caveat, none of which appear in 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?

Front-loaded with the core return statement, then usage, then pagination, then alternatives. Very dense and every sentence carries information, though the middle section packs defaults and filter caveats into long clauses that slightly strain readability.

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 10 parameters, no output schema, and read-write side effects, the description covers the return shape (metadata entries and the sender_t3_thread field), pagination, defaults, and the alternatives. An agent has everything needed to call 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 the baseline is 3, but the description adds semantics the schema lacks: pagination loop behavior, the interaction between include_bodies and mark_read defaults, that filters combine, and what sender_t3_thread means ('null outside T3'). It adds genuine value beyond the field descriptions.

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 an array of your latest received message metadata, newest first.' It also names sibling tools for adjacent jobs (search_messages, mark_message_read, acknowledge_message), but it never distinguishes itself from fetch_session_inbox, the closest sibling, leaving that boundary ambiguous.

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 when-to-use with concrete parameter recipes: 'At session start or after a mail notice, set unread_only:true, include_bodies:true and mark_read:true.' It also states exclusions and alternatives: 'Use search_messages for project-wide text matching, or mark_message_read or acknowledge_message for one message.' Nothing 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?

Beyond the annotations (which only say readOnlyHint=false, idempotent=false), the description discloses the mutating side effect of the default mark_read:true, all four defaults, the drain semantics and termination condition, and the security model ('trusted local service; session identity selects inboxes and is not authentication'). This is unusually rich behavioral context for a fetch 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 purpose is front-loaded in sentence one and subsequent sentences carry operational payload (defaults, drain algorithm, auth model). It is dense and a couple of clauses (e.g. the receipt project_key/agent_name note) are lower-value, but nearly every sentence earns its place given the absence of an output 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 no output schema, the description compensates by sketching the return shape ('Each receipt includes project_key and agent_name for replies and acknowledgements'), the pagination/drain model, and the identity/auth assumptions. For a 7-param, session-scoped fetch tool this is complete enough to invoke 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 schema already documents each parameter, establishing a baseline of 3. The description meaningfully adds semantics: it states defaults inline, explains limit's drain-loop implication (fewer than limit returned = done, capped at 1000), and clarifies t3_thread is used 'when known' and that host/session_id must be machine-derived rather than guessed.

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 (Return), resource (one newest-first page), and scope (registrations matching your host/session tag or T3 thread), which makes the tool's remit clear. It stops short of naming the sibling fetch_inbox to explicitly differentiate, but the session-scoped framing 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?

It gives explicit when-to-use and how-to-use guidance: prefer machine-derived host/session_id and t3_thread 'when known', 'never guess from an agent name', and the drain loop ('stop when fewer than limit messages return... repeating only after a full page'). It also states the negative case: with mark_read:false or unread_only:false it is 'a bounded preview, not a drain'.

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 provide coarse hints (readOnlyHint false, destructiveHint false); the description adds substantial behavior beyond them: the exact return shape {granted, conflicts}, that conflicts do NOT fail the call, that nothing blocks the edit itself, the git-guard behavior for commits, that re-reserving an already-held path updates it, and the expiry model. This is rich, non-obvious 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?

Front-loads the core purpose in the first sentence, then layers return shape, conflict behavior, and lifecycle routing. Dense and largely waste-free, though the git-guard sentence is somewhat tangential to selection and could be trimmed.

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 compensates by spelling out the return object ({granted, conflicts} and their contents) and the non-failing conflict semantics. Combined with the fully documented schema, an agent has everything needed to call and interpret 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 100%, so the schema already documents all seven parameters, setting the baseline at 3. The description adds only marginal parameter-level meaning (re-reserving updates an existing hold) and does not clarify semantics like ttl_seconds or idempotency_key beyond what the schema states.

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 (Reserve) and resource (repository-relative paths or globs) plus the intent ('so other agents know what you are editing'). It is clearly distinguishable from the sibling renew_file_reservations and release_file_reservations, which the description explicitly names.

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?

Names the lifecycle alternatives explicitly ('Extend with renew_file_reservations and release with release_file_reservations when done'), giving clear context for related actions. It does not state when not to reserve, so it stops short of full 5-level guidance, but routing to siblings 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?

Annotations only declare readOnlyHint/openWorldHint, but the description adds substantial behavioral context: admission observations are historical and null means no snapshot, null timestamps are not errors, and storage/read/ack do not imply task acceptance. It also discloses the NOT_FOUND failure mode, which annotations cannot express.

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 return payload, then adds the semantic caveats and the role-based routing. Dense but every sentence carries distinct information; only minor tightening is possible.

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 an output schema exists, the description need not document returns, yet it still covers role applicability, null-value semantics, non-equivalence of ack and acceptance, and the failure condition — everything an agent needs to interpret results 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 goes beyond the schema by stating message_id 'must exist in this project or the call fails with NOT_FOUND,' adding an error constraint not captured in the property docs.

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 (Return) and resource (a message's delivery receipt), and enumerates the fields returned (persisted_at, recipients, read_at, acknowledged, admission). It also distinguishes itself from the sibling fetch_inbox by naming which role uses which tool.

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 by role: 'Use it as the sender to check an ack_required message; recipients use fetch_inbox.' Names both the condition for use and the alternative tool, leaving nothing 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 and openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: it reports both server and database reachability and includes the database path, and frames the tool as a failure-triage probe.

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 load-bearing: the first states what is reported, the second states when to call it and why. Front-loaded with the outcome, 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?

There is no output schema, but the description explains what the result conveys (server and database answering, plus the database path). For a zero-parameter diagnostic tool with read-only annotations, 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 schema has zero parameters, so the baseline is 4. There is no parameter semantics to convey, and the description correctly does not fabricate any.

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 (report) and resource (server and its database), plus the returned datum (the database path). No sibling tool in the list performs diagnostics, so it is trivially distinguished from the agent/messaging/reservation 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?

It gives an explicit trigger (when another tool fails with an INTERNAL error or no answer) and the diagnostic intent (distinguish a down server from a bad request). An agent knows exactly when to reach for this versus retrying or fixing a request.

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 cover readOnlyHint and openWorldHint, and the description goes well beyond that: result ordering, the no-continuation-cursor limitation, and the warning that metadata/activity do not prove current session or model liveness. That liveness caveat is genuinely non-obvious behavioral context. It does not, however, discuss cost, scale limits of the underlying query, or failure modes.

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 return shape before usage guidance, and every sentence carries information. It is dense with three distinct caveats in one paragraph, which is slightly heavy for a single-blurb description but not 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 no output schema, the description carries the burden of describing returns and does so ('program, model, task and session details, including t3_thread'). Combined with the truncation and liveness caveats, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: active_within_days 'filters recent activity, not whether a session is running' and limit 'caps this single result; there is no continuation cursor, so a full result may omit agents.' These clarify semantics the schema's terse parameter descriptions do not.

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 an array of non-retired agents in a project'), its ordering ('most recently active first'), and the returned fields. It also explicitly distinguishes itself from the sibling whois ('whois returns one agent'), so an agent can pick correctly 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?

Gives an explicit use case ('find who to message') and names the competing alternative with its differing cardinality. It also warns that active_within_days filters recent activity rather than whether a session is running, which prevents a plausible misuse of the parameter as a liveness filter.

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 non-idempotency, and the description adds real behavioral context beyond them: the inbox does not mark mail read, conflicting paths surface under file_reservations.conflicts while other paths are granted. It does not explain the destructive/non-idempotent implications (e.g. what a re-run destroys), leaving a small gap.

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 list and return shape, then the mail/conflict caveats, then the alternative. Dense but each sentence carries information; no wasted preamble.

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 10-parameter macro with no output schema, the description compensates by enumerating the returned keys and clarifying conflict behavior, which is exactly what is missing structurally. It is nearly complete, though it could say more about the destructive/non-idempotent re-invocation semantics.

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 meaning beyond the schema by telling the agent to reuse the hook's agent_name or paste its session tag into task_description to avoid a duplicate identity. Other parameters are 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 compound action (ensure project, register agent, optionally reserve paths, return {project, agent, file_reservations, inbox}) with a clear verb+resource framing. It explicitly distinguishes itself from the sibling fetch_inbox, so an agent can tell them apart 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?

Names the alternative (fetch_inbox) and the exact conditions that select it: for message bodies, for unread-mail draining, and 'If already registered and only checking mail.' It also gives the positive routing hint about reusing the hook's name or session tag to avoid a second identity.

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?

Discloses behavior annotations do not cover: the returned fields, the repeat-call semantics (first read time retained, activity time refreshed), and the NOT_FOUND error condition. With readOnlyHint=false the mutation nature is already flagged, and the description enriches it rather than contradicting 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?

Five compact sentences, front-loaded with the core action and return value, followed by edge cases and the alternative tool. No filler and 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?

With no output schema, the description compensates by naming the return fields (message_id, read, read_at), and it covers the error path and the sibling-tool boundary. An agent has everything needed to call 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 three parameters are documented in the schema. The description adds only implicit scope ('received message' implies you must be a recipient) and no format or syntax detail beyond that, 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 (mark read) and resource (one received message), plus the key differentiator that it does not acknowledge it. The agent can distinguish this from acknowledge_message and fetch_inbox 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?

Explicitly routes: use acknowledge_message when ack_required is set, and notes fetch_inbox already marks messages unless mark_read:false. It also states the failure precondition (NOT_FOUND unless you are a recipient). This is exactly the when/when-not/alternative guidance expected.

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 non-idempotent, so the baseline is lower, yet the description goes well beyond them: it discloses project creation, generated naming, session-tag-driven update of an existing agent, that re-registration overwrites program/model/task and clears inactivity retirement, and that lifecycle closure needs a verified reopen. These are exactly the overwrite side effects an agent must know before calling.

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 main purpose is front-loaded, but the middle sentences stack convoluted conditionals ('unless task_description starts with a session tag an eligible or lifecycle-bound agent already has') and the hook/name guidance partly repeats the earlier session-tag rule, so some content does not fully earn 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 complex, non-idempotent mutation tool with no output schema, the description covers side effects, naming, re-registration, hook interplay and the alternative macro_start_session. It is largely complete, though it does not say what the call returns (e.g., the assigned name/identity) or what happens on failure.

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

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

Schema description coverage is 100%, so the baseline is 3. Most of the description's parameter guidance (omit name to get one generated, keep the leading session tag in task_description) restates what the schema already says, and the genuinely new cross-parameter rule (a session tag in task_description selecting an existing agent) is only lightly elaborated, so it adds limited 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 first sentence states a specific verb+resource with scope: 'Register or update an agent identity in a project, creating the project if needed.' It also names a sibling alternative (macro_start_session) and the conditions that distinguish it, so the agent can tell it apart 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?

The description gives concrete conditions: omit name for a generated name, re-register to replace program/model/task, and use macro_start_session to also reserve paths and read inbox in one call. It stops short of an explicit 'do not use when' case, but the alternative routing is clear enough for correct selection.

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 non-idempotent behavior, so the safety profile is covered. The description adds genuinely non-obvious behavior: the return value semantics ('returns how many were released') and that a zero count is not an error — a real anti-confusion signal. It does not restate that release is irreversible, but that is already implied by destructiveHint.

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 and the timing rule, then filter semantics, then return behavior. Every sentence carries distinct information; no repetition of the name or schema 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 4-param, no-output-schema mutation tool this is nearly complete: it covers when to call, how filters combine, and what the return count means. Minor gaps remain (nothing about reservation expiry or whether release is scoped per-project), but nothing that would cause a misinvocation.

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 goes further by defining filter interaction semantics the schema does not: empty filters impose no restriction, and two nonempty filters must both match. That clarifies the AND/OR behavior of paths vs file_reservation_ids, which the terse schema strings ('Only your reservations with exactly these patterns') do not.

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 (release active file reservations) and immediately frames the agent's situation ('when you finish work'). It is cleanly distinguished from the sibling renew_file_reservations, so no schema browsing is needed to tell them apart.

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 and the condition that selects it: use renew_file_reservations while work continues, use this when work finishes. It also spells out the filter decision (omit both to release all, supply paths or ids for a subset), leaving nothing 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 non-readonly, non-idempotent, non-destructive, but the description adds real behavioral context: repeated calls stack extensions, expired reservations are silently skipped, no matches returns zero with an empty array, and the response shape {renewed, file_reservations} with old and new expiries. This goes well 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 core action and scope before filtering rules and return/edge-case detail. Dense but nearly every clause carries needed information; the return-shape clause is arguably the most expendable but still useful.

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 present, the description compensates by describing the return payload and the zero-match case. Combined with 100% schema coverage and annotations, an agent has everything needed to invoke and interpret this 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 adds genuine meaning the schema does not: the interaction rule that two non-empty filters must both match and that omission or empty filters impose no restriction. It adds combinatorial semantics rather than just restating field docs.

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 ('extend your active reservations by extend_seconds past their current expiry') and immediately differentiates from siblings by naming file_reservation_paths for the expired case. An agent can distinguish this from file_reservation_paths and release_file_reservations without opening 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 covers the when-not case ('Expired reservations are not renewed; reserve them again with file_reservation_paths') and gives the alternative tool by name. It also clarifies filter-combination behavior (omit both for all, empty imposes no restriction, two nonempty must both match), leaving little to inference.

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

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

With annotations present (readOnly false, idempotent false, destructive false), the description adds real behavioral context: subject/topic/importance inheritance with a 'Re:' prefix, importance override, ack_required defaulting to false, and 7-day idempotency_key replay semantics. Some of this (idempotency, notification_policy, delivery_policy detail) duplicates the schema rather than extending it, which keeps 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?

The core purpose is correctly front-loaded in the first two sentences, but the remaining ~400 words are largely prescriptive prose style rules (Markdown formatting, action-first openings, Evidence/Next action lines, T3 thread-link conventions, agent naming) that are tangential to invoking a reply tool. The volume buries the operational parameters and makes the definition hard to scan.

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 13-parameter mutation tool with an output schema, the definition covers selection, defaults, inheritance behavior, idempotency/retry, delivery and notification policy, and conflict error naming (IDEMPOTENCY_KEY_CONFLICT). Nothing an agent needs to call it correctly is missing; return-value detail is rightly delegated 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 description coverage is 100%, so the baseline is 3 and the schema already documents each parameter. The description nonetheless adds defaults not obvious from the schema itself: 'to' omitted addresses the sender, cc/bcc added only when supplied, importance inherited unless overridden, and ack_required defaulting to false.

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 gives a specific verb and resource ('Reply in a message's thread') plus the return behavior ('returning the stored message with reply_to') and the key selector ('message_id selects the original in this project'). It also explicitly distinguishes itself from send_message ('To start a new thread, use send_message'), so an agent can pick between the two siblings 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?

The description states when to use this tool versus alternatives in multiple places: send_message for new threads, resource_notice for typed release/cancellation mail, and explicit exclusions ('do not send courtesy acknowledgements or reply to thanks'). It also supplies the trigger conditions ('Send only when the recipient needs to act or know: a handoff, requested result, blocker or shared-resource change'), leaving little to inference.

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

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

Annotations only declare mutation/non-idempotent flags; the description adds substantive behavior: it releases owned resources, finishes dependency notices, retires the registration across every joined project, removes the agent from list_agents so new messages fail, preserves existing messages, and is reversible by unretire_agent or by the agent simply acting again. That is well beyond what the flags 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 dense sentences; the primary use case and the safety precondition come first, followed by effects and reversibility. Every sentence earns its place, though the run-on constructions could be trimmed for scanability.

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, yet the description covers the trigger condition, the prerequisite for retiring others, observable side effects, message preservation, and reversal semantics — everything needed to invoke this safely without ambiguity.

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 both agent_name and project_key are already documented, and the description adds no format or syntax detail for them. It does hint at multi-project scope ('in every project you joined'), which sits slightly awkwardly against the single required project_key, but this is not clarified further. 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 — 'retire your own registration' / 'retire an agent' — and immediately contrasts with the inverse tool unretire_agent. An agent can distinguish this from register_agent, whois, and list_agents 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 states when to act ('At an agreed whole-session closeout or a whole-session completion with nothing remaining') and adds a hard prerequisite for third-party retirement ('confirm with its owning host that its session has ended; roster data or a ping timeout is insufficient'). It also names unretire_agent as the reversal path, so alternatives are covered.

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 readOnlyHint annotation, the description discloses that mail is not marked read, that excerpts are capped at 512 code points with >>>matched text<<< markers, that all query words must match, and that pagination requires keeping query/filters/ranking unchanged. These are concrete operational details annotations cannot 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?

Dense but front-loaded, leading with the verb, scope, and return shape before the behavioral and pagination rules. Every sentence conveys a distinct constraint or routing hint 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 an 11-parameter search tool with no output schema, the description supplies the return structure ({result, next_cursor?}), pagination semantics, excerpt format, and alternative-tool routing. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: cursor reuse semantics ('keep query, filters and ranking unchanged when passing next_cursor'), include_body_md behavior, and ranking's effect on result order. It does not explain every parameter, but the ones it covers gain genuine context.

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 ('Search subjects and bodies across a project') plus the return shape and a behavioral guarantee (does not mark mail read). An agent can distinguish it from fetch_inbox and summarize_thread 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?

Explicitly routes the agent: 'Use fetch_inbox for your received unread mail, or summarize_thread for a thread's participants and recent messages.' This names both alternatives and the conditions that select them, leaving nothing 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 only declare the coarse flags (non-read-only, non-destructive, not idempotent, closed-world). The description goes well beyond them, disclosing failure semantics (unregistered/retired/closed recipient fails the whole send with persisted:false and a reason), the 7-day idempotency replay window versus a duplicate-on-retry default, that replay observations are historical, that storage is not task acceptance, and the transport rule against re-routing on uncertain delivery. The idempotentHint:false annotation is not contradicted: it correctly describes the keyless default path that the description qualifies.

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 dense wall of prose that mixes invocation-critical facts with message-composition style coaching (open with the action, add up to three short facts, add a Next action line, put hashes and metrics in linked records, use spaces between words and numbers). Those craft instructions crowd out the routing and failure facts and are not front-loaded, so the piece is over-specified rather than concise even though individual sentences are grammatically tight.

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 15-parameter tool with nested oneOf branches, an output schema and annotations, the description covers the important gaps: mutating nature, recipient failure modes, idempotency, notice-mode constraints, threading and transport selection. The only shortfall is that the crucial branch conditions (resource_notice vs subject/body_md) are buried mid-paragraph, so completeness is achieved at the cost of discoverability.

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: the resource_notice branch is summarized as "one recipient, a nonempty idempotency key, no free-text or delivery overrides," the idempotency_key replay/conflict contract is restated operationally, and the descendance rule (only contact still-dependent resource owners, send release/cancellation before dropping waiting recipients) constrains how parameters should be used. It clarifies the oneOf branching that the schema only expresses structurally.

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?

Opens with a specific verb+resource+scope: "Send a Markdown message to named agents in the same project." It explicitly distinguishes itself from the nearest sibling (reply_message) and from resource_notice mail, so an agent can route correctly 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?

Gives explicit inclusion criteria ("Send only when the recipient needs to act or know: a handoff, requested result, blocker or shared-resource change") and exclusions ("do not send courtesy acknowledgements or reply to thanks"), plus a named alternative with its selecting condition ("To answer a message, use reply_message"). This is textbook when/when-not/alternative 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?

Substantially exceeds what annotations convey: stale revisions fail before a matching-value no-op, edits are metadata-only (no new inbox notice or repeated instruction), priority grants no authority, and identical retries replay ahead of activation/lifecycle/revision checks. The idempotentHint and destructiveHint annotations are corroborated and elaborated rather than merely restated.

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 purpose, then preconditions, return values, and failure/activation semantics. Dense but every clause carries operative information about revisions, idempotency, or activation; 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?

No output schema exists, yet the description enumerates the return fields (message_id, revision, importance, changed), covers the revision-conflict path, metadata-only effects, idempotent replay, and the server-activation requirement. An agent has everything needed to invoke and interpret 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 the baseline is 3, but the description adds genuine semantics: it identifies where expected_revision must come from (inbox, history or sender receipt) and states the ordering rule that a stale revision fails before a matching-value no-op can occur, which the schema does not express.

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 with explicit scope: 'Change only your message's low/normal/high/urgent priority.' The word 'only' plus the enumerated values make clear this targets the importance field alone, distinguishing it from sibling mutators like reply_message or acknowledge_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?

Gives clear preconditions: requires a current expected_revision sourced from inbox, history or sender receipt, plus a nonempty idempotency_key, and notes the tool requires explicit server activation. It does not name an alternative tool or state when-not to use it, 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?

Goes well past the readOnlyHint/openWorldHint annotations by disclosing that it does not generate prose and does not mark mail read, that there is no continuation cursor, and that total_messages counts the entire thread even when messages is truncated. These are exactly the behavioral traits an agent needs beyond structured hints.

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?

Return shape is front-loaded and every sentence carries distinct operational information (return format, non-actions, id sourcing, limit behavior, no-cursor, empty-thread case). It is dense but not padded, staying a single tight paragraph.

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, yet the description fully specifies the return shape, truncation semantics, and the zero-message case, so the agent has everything needed to call and interpret results 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 already 100%, so the baseline is 3, but the description adds real meaning for per_thread_limit: newest messages with full bodies, returned oldest first, default 50, cap 1000. The thread_id sourcing hint also aids interpretation 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?

States a specific verb+resource and, crucially, clarifies the tool returns structured data {thread_id, summary:{...}, messages} rather than generating summary prose. It distinguishes itself from search_messages and fetch_inbox by scope, so an agent can choose without opening sibling 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 routes the agent: find thread_id via search_messages or fetch_inbox, use search_messages for text matching, fetch_inbox to drain unread mail. Names both alternatives and the condition that selects each, leaving nothing 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing that earlier messages are unchanged, that the return is {agent_name, retired:false}, that the call refreshes activity time on every revival, and that an unknown name fails with NOT_FOUND. It does not mention permission or auth requirements, which keeps 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?

Purpose is front-loaded in the first clause, followed by return shape, idempotent-like behavior, and the auto-revival alternative. Every sentence carries information, though the enumeration of auto-revival triggers makes it slightly denser than necessary.

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 compensates by specifying the return object and the failure mode, and it resolves the sibling ambiguity against retire_agent and list_agents. Nothing an agent needs in order 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?

Schema description coverage is 100%, so both parameters are already documented in the schema; the baseline of 3 applies. The description adds the NOT_FOUND behavior for an unknown agent_name, but says nothing about project_key and adds no syntax or format 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?

States a specific verb+resource ('bring a retired agent back into list_agents') plus the resulting effect ('can receive messages again'), which cleanly separates it from the sibling retire_agent. 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?

Explicitly identifies the alternative path: registering, sending, reading mail, or reserving files revives the caller automatically, so this tool is for reviving ANOTHER agent. It also states the already-active case succeeds, removing ambiguity about whether to guard the 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses real behavioral traits: unknown names raise NOT_FOUND and surface recently active agents as a hint, t3_thread is null outside T3, and profile activity does not mean the session is live. That last caveat is a genuinely useful warning not derivable 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?

Three tight sentences, front-loaded with what the tool returns, followed by error behavior and the sibling pointer. The mid-sentence field enumeration is dense but each clause carries information; nothing is 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 no output schema, the description must carry the return shape, and it does by listing every returned field plus the null semantics of t3_thread. Error behavior, the staleness caveat, and the sibling alternative are all present, so an agent has what it needs to call and interpret 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 description coverage is 100% and both parameters are documented in-schema, so the baseline is 3. The description adds only indirect semantics via the NOT_FOUND behavior tied to agent_name; it does not explain the expected format for agent_name or project_key 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?

Specific verb (return) plus singular resource (one agent's profile), and it enumerates the returned fields (program, model, task description, t3_thread, activity times). It explicitly distinguishes itself from list_agents, so an agent can route between the two 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 names the alternative for the plural case ('To see every agent in a project, use list_agents'), which is explicit routing guidance. It does not spell out exclusions or preconditions (e.g. when an agent lookup is unnecessary), so it falls short of the full when/when-not treatment.

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 destructive and idempotent, but the description adds substantial context beyond them: content and audit history are retained, server activation after reader qualification is required, previews/injected context are not recallable, and idempotency-key replay behavior (including replay while execution is disabled or sender closed). This is a genuinely richer behavioral profile than the annotations alone.

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

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

Front-loaded with the operation and its scope, then layered with return values, recipient rules, retention guarantees, and activation/idempotency constraints. Every sentence carries new 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?

No output schema exists, yet the description names the return fields (message_id, revision, per-recipient withdrawn/already_withdrawn/too_late results), states retention behavior, and covers the activation prerequisite and idempotency contract. 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 description coverage is 100%, so the baseline is 3 and the schema already documents all five parameters. The description nonetheless adds meaning beyond it: the recipients parameter's subset-validity and omit-for-all semantics, and the replay/conflict behavior of the idempotency key, are reinforced in context rather than left purely 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 (withdraw) applied to a specific resource (your message) with an explicit scope limit (recipients whose delivery has not been read, acknowledged or withdrawn). This clearly separates it from siblings like acknowledge_message, mark_message_read and send_message 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 clear applicability conditions: it only affects unread/unacknowledged/unwithdrawn deliveries, recipients may be omitted for all or given as a nonempty valid subset, and previews/injected context cannot be recalled. It doesn't explicitly name an alternative tool, so it falls short of a full 5, but the context for use is unambiguous.

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