Mara Briefing Service

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

With no annotations, the description carries the full burden and does well: it discloses the privilege requirement (admin secret), the mutation (marks fulfilled), and the downstream effect (stored text is served by get_briefing). It omits idempotency and failure behavior, keeping it out of 5 territory.

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 with the access restriction front-loaded and zero filler; every clause adds distinct information (auth, mutation, side effect).

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 auth, mutation, and the consumer relationship. Only edge-case behavior for invalid or unpaid requests 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?

Schema description coverage is 0%, so the description must compensate. It clarifies that briefing includes sources and that admin_secret is a secret credential, but request_id semantics (who issues it, format) are left entirely to inference.

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: marks a paid request fulfilled and stores the completed briefing. It also names the sibling that consumes the result (get_briefing serves it), so an agent can separate this write-side tool from the read-side one 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?

'Admin only' and 'Requires the admin secret' set clear preconditions for invocation, and the get_briefing reference implies the fulfillment workflow. It stops short of stating when NOT to use it or what to do if the request is unpaid, so it is clear context rather than full routing guidance.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious state semantics: the call is free, and the result may be an in-progress marker ('paid_queued') or a finished briefing with sources. It does not mention whether the call blocks, whether polling is expected, or auth requirements, so it is good but not complete for an unannotated 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?

Three short sentences, front-loaded with the action and provenance, then the two possible response states. Tight and readable, with only minor redundancy between 'Free' and the rest of the framing.

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-shape detail is not required, yet the description still adds useful status semantics ('paid_queued' vs completed with sources). For a one-parameter read tool the main remaining gap is the undocumented request_id and the absence of any auth/polling note.

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 0% and the description never names or describes request_id — its only clue is the phrase 'requested via request_briefing', which lets an agent infer provenance but not format or validation. With the single parameter entirely undocumented in both places, the description fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Retrieve a briefing') and explicitly anchors it to the sibling that creates the resource ('requested via request_briefing'). An agent can distinguish this retrieval tool from request_briefing/fulfill_briefing 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 reference to request_briefing implies the prerequisite (a briefing must already have been requested) and 'Free' flags that no cost is incurred, but there is no explicit when-to-use vs. fulfill_briefing/list_queue guidance or any when-not condition. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden: it discloses the admin-secret auth requirement, the newest-first ordering, and the default status. It omits pagination behavior, the meaning of limit, and what the result set looks like, so a mutation-free read tool is only partially characterized.

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 with the auth gate and ordering front-loaded. No filler, though the parenthetical value list could be slightly more compact.

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

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

An output schema exists, so return values need not be described, and auth is covered. Still missing is any handling of the limit parameter or pagination semantics, which an agent needs to call a list tool predictably.

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 0% and the status parameter is not declared as an enum, so the description's enumeration of valid values ('paid_queued' or 'fulfilled') adds genuine meaning beyond the schema. However, the limit parameter and its default are never explained, so compensation is incomplete.

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 ('Lists briefing requests') plus ordering ('newest first'), which is enough to distinguish it from the single-item get_briefing sibling. It stops short of explicitly naming how it differs from fulfill_briefing or request_briefing.

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 the admin-only preconditions and the optional status filter, implying when the tool applies. It never states when to reach for this instead of get_briefing or fulfill_briefing, so the alternative-selection guidance 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?

With no annotations, the description carries the full burden and does so well: it discloses cost ($0.10 USDC on Base Sepolia), the x402 two-step handshake (call once without payment to get terms, then retry with signed payment in _meta['x402/payment']), and that work is asynchronous via a request ID. These are exactly the operational traits 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?

Three dense sentences, front-loaded with purpose, then mechanism, then payment. Every clause carries information, though the payment sentence is long and slightly compounds two ideas (cost and the retry protocol).

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 explains what comes back (a request ID) and how to use it (get_briefing). With the cost, payment protocol, and async retrieval all documented, an agent has everything required to call this tool correctly on the first attempt.

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

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

Schema coverage is 0% for the single 'question' parameter, so the description must compensate, and it does: 'Provide a question or topic' conveys that free-form natural-language input is expected. It does not describe length limits or formatting, but the semantic intent is covered adequately for a one-param tool.

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 ('Request a sourced research briefing from Mara, an AI research agent') and clarifies the output is a request ID rather than the briefing itself. It partially distinguishes from siblings by naming get_briefing as the retrieval path, but does not contrast with fulfill_briefing or list_queue, which sit in the same queue-oriented family.

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 for invocation ('Provide a question or topic') and an explicit follow-up path ('can be retrieved with get_briefing'). It also spells out the payment precondition, which tells the agent when the tool will succeed versus return payment terms. No explicit when-not-to-use guidance or comparison to fulfill_briefing is offered.

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 no annotations, the description carries the full burden. It adds 'Free' as a cost trait and implies a read-only return, but does not state authentication needs, side effects, or explicit safety guarantees.

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 tightly written sentence with the important cost qualifier front-loaded. Every phrase earns its place and nothing is verbose.

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

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

The output schema already describes the return structure, and the description correctly focuses on what the card contains. It is nearly complete, though a brief note on read-only safety or calling context would make it fully self-contained.

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

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

The tool takes zero parameters, so there is nothing to document beyond the schema. The baseline for zero-parameter tools is 4, and the description adds no parameter detail because none exists.

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 (Returns) and resource (this service's agent card), and enumerates the contents (who Mara is, pricing, terms). It is clear what the tool does, but it does not explicitly differentiate itself from the briefing-related sibling 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?

The description offers no when-to-use guidance or alternatives. 'Free' hints at cost, but there is no context about when an agent should call this versus other tools.

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