Odile Gate

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

Adds genuinely useful context beyond the annotations: the app key is returned only once, and routes are stored as enforceable rules. Annotations already imply mutation (readOnlyHint false, non-idempotent), so the remaining gaps (rate-limit interplay, failure modes) are minor.

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 and the return-value caveat, and every sentence carries content. The route examples are dense but place the semantics up front without wasted words.

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 correctly tells the agent what comes back (the app key, shown once). Prerequisites are partly covered in the schema, so only routing specifics or rate-limit behavior are left thin.

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 meaningfully elaborates 'routes' beyond the schema: pattern rules like 'GET /orders/:id', per-user paths, and concrete example calls that become rules. That adds interpretation the schema does not provide.

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 action: registering one app with its own key and the exact calls it may make. Identifies the return value (the app key) and makes clear this is app-level scoping, which separates it from gate_create_project and gate_add_approver.

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?

Conveys the general intent (give an app its key and rules) but never says when to use this versus gate_set_app_runs or other siblings, nor that project_id/admin_key must already exist from gate_create_project. No when-to-use or exclusion 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 only carry the generic safety profile (readOnly=false, idempotent=false), so the description does real work here: it warns the key is shown once, that it must go to a human not an agent, and that adding an approver permanently disables admin-key approval. That is meaningful behavioral context beyond structured fields.

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

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

Two tight sentences with no filler. The core action is front-loaded and the cautionary constraint follows immediately, so 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?

There is no output schema, but the description covers the key return behavior (shown once). Combined with annotations covering the safety profile, an agent has enough to call this correctly; only the exact return shape is unstated.

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

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

Schema description coverage is 100% and the schema already documents name, admin_key, and project_id well. The description adds no syntax or format detail beyond what the schema provides, 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?

The description uses a specific verb+resource ("Create an approver key") that is clearly distinct from sibling tools like gate_add_app or gate_create_project. It does not, however, explicitly name or contrast against any sibling, so it stops short of the top tier.

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 important when-not rule ("never to an agent") and a consequence for use (admin key can no longer approve), which implies context. But there is no explicit statement of when to reach for this tool versus gate_add_app or other authorization tools, leaving routing 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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond them: newest-first ordering, aggregate totals by status and refusal reason, and the privacy guarantee that bodies, query values, and headers are never stored.

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 dense sentences with no filler: the first front-loads what is returned and in what order, the second adds the privacy constraint that an agent or user would care about.

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 what comes back and does so well: fields, ordering, and rollup totals. Pagination and what happens when limit exceeds available calls are not covered, a minor gap for a capped list tool.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the limit default and the app/status filter syntax. The description adds only the implicit notion of 'most recent calls' and does not clarify filter interaction beyond the schema. 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 resource (recent calls through the gateway) and enumerates the fields returned (time, app, matched route, status, reason, duration). It does not contrast itself with the closest sibling, gate_explain_refusal, so the agent must infer which one answers 'why was this refused'.

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

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

Usage is only implied: it is for reviewing recent traffic and refusal totals. No when-to-use, when-not-to-use, or explicit alternative (e.g., gate_explain_refusal for a single refusal) is named.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely useful behavior the annotations do not: the admin_key is shown only once (an irrecoverable secret), and the returned gateway base URL is what apps must call instead. Auth requirements and rate limits remain undisclosed.

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

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

Two sentences, zero filler, and the core action is front-loaded ahead of the return-value detail. Every clause 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?

With no output schema, the description carries the return-value burden and does so well (project_id, one-time admin_key, gateway base URL). What remains thin is setup context — no mention of auth requirements or follow-up steps such as registering apps against the new project.

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 four parameters including the https-only upstream constraint and the encrypted header_value. The description adds no parameter syntax or format detail beyond reinforcing the HTTPS upstream requirement, 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 concrete action (put Odile Gate in front of an existing HTTPS API) and names the three artifacts produced. An agent can tell this is the project-creation entry point rather than an app/approver mutation, though no sibling is named 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?

The phrase 'in front of an existing HTTPS API' implies the prerequisite context (an HTTPS upstream must already exist), but there is no explicit when-to-use statement, no ordering guidance relative to gate_add_app, and no 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 cover read-only/open-world/idempotency; the description adds genuinely non-obvious behavior: the token is shown exactly once, permissions expire, and write calls inside a run require an Idempotency-Key. That is real operational context beyond the structured fields, though it does not say what happens on expiry or whether runs can be revoked.

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 the purpose, then the actions/scope model, then the return value and required header. Every sentence conveys information an agent needs to act on the result.

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

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

For an 8-parameter nested-object creation tool with no output schema, the description covers the essentials: what is created, how actions/scope interact, that a token is returned once, and how to use it. Missing only edge behavior (expiry, revocation, failure modes), which is minor relative to what is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the concept behind 'actions' (rules with {placeholders} bound by scope, each with optional max and approval) and gives a concrete example rule+scope pair. This adds meaning the schema's terse field descriptions do not carry.

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 ('Gate Actions: give one agent session narrow, expiring permission') and what it produces (a run token). It is clearly a creation tool, but it never names a sibling such as gate_set_app_runs or gate_add_app to sharpen the boundary.

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

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

Usage context is implied: narrow, expiring permission for one agent session, and the optional ttl_seconds/max_calls language supports that. It also explains the follow-up obligations (send x-odile-run with app key, Idempotency-Key on writes), but there is no explicit when-not guidance or named alternative.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds the key behavioral context that this is diagnostic lookup driven by a header value rather than a general audit endpoint. It doesn't state the form of the returned explanation, but as a read-only explainer with no side effects that gap is minor.

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, and the purpose is front-loaded before the input source. Nothing should 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?

For a one-parameter read-only tool with no output schema, the definition covers purpose, input provenance, and the nature of the response ('what it means and how to fix it'). Only a hint about the explanation's structure is missing.

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

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

Schema coverage is 100% and the single param is well documented, but the description still adds value by naming the concrete source (the x-gate-refused header) and giving a real example value, disambiguating the free-form string the schema leaves open.

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 (explain) and resource (a Gate refusal), plus what the answer contains: meaning and remediation. The example value 'route_not_allowed' makes the scope concrete and distinguishes it from the sibling gate_* tools that manage apps, runs, and audits.

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 exactly when this tool applies: when an x-gate-refused header value is present, that value is the input. There is clear context but no explicit statement of alternatives or exclusions (e.g. what to do if no refusal occurred).

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=true, so safety is covered. The description adds meaningful context beyond that: approval is a human dashboard action, which stops an agent from hunting for an approve tool. It says nothing about pagination or result volume, 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?

Two short sentences, front-loaded with what the tool returns followed by the approval constraint. 'With the exact call' is slightly cryptic but no sentence is wasted.

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

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

With no output schema, the description compensates modestly by indicating the listing includes the exact call being held. Combined with annotations covering read-only behavior and the note about human approval, an agent has enough to invoke it correctly, though the result shape and pagination remain unspecified.

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 enum states, admin_key, and project_id are already documented in the schema. The description only alludes to alternate states ('or in another state') without adding syntax or default behavior beyond what the schema states. 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 ('list' held actions waiting for approval) and clarifies contents ('with the exact call'). It is distinguishable in spirit from gate_list_apps or gate_audit, though it never names or contrasts with those siblings directly.

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

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

The description implies usage (fetch held actions and their states) and usefully notes that approving happens in the dashboard, not via a tool. It does not state when to prefer this over gate_audit or gate_explain_refusal, so the routing guidance is only partial.

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=true, so the safety profile is covered. The description's only added behavior is naming what comes back (allowed calls, limits, state), which is mildly useful given there is no output schema; it says nothing about ordering, size, or failure on an unknown project_id.

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

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

A single short fragment with zero filler; nothing in it is wasteful. It is arguably under-specified rather than over-long, but on pure economy and front-loading it scores well.

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 bears the burden of describing the result, and it does so only minimally (apps plus their allowed calls, limits and state). Parameters are fully covered by the schema, so the remaining gap is thin return-value and error detail.

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 (admin_key, project_id) are documented in the schema with format and provenance. The description adds no additional parameter 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?

The description is a noun phrase ('The project's apps with their allowed calls, limits and state') rather than a verb+resource statement; the verb 'List' only appears in the title. The resource is unambiguous and it is distinguishable from gate_add_app by the field list, but the actual operation 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 when-to-use guidance, no prerequisites, and no mention of alternatives such as gate_add_app for adding an app or gate_set_app_runs for changing run state. The agent must infer that this is the read path for an existing project.

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

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

Annotations already disclose the safety profile (not read-only, idempotent, not destructive, open world). The description adds valuable semantics for each mode, but does not cover side effects, permission requirements, or interaction with existing runs.

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 waste, front-loading the core action and then defining each mode. No unnecessary preamble 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?

For a mutation tool with no output schema and annotations covering safety, the description provides the critical mode semantics. It could mention permission needs or effects on existing runs, but the essentials are present.

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

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

Schema coverage is 75%, and the description meaningfully explains the mode parameter ("writes", "all", "off") beyond the raw enum values. The other three parameters are already documented in the schema, so the description compensates well for the one 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 ("make an app need a run") and resource ("an app") with the available modes enumerated. It does not explicitly distinguish this tool from siblings like gate_add_app or gate_create_run, but the purpose is clear.

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

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

The description implies usage via "Make an app need a run" but gives no explicit when-to-use guidance, prerequisites, or alternatives to consider. The implied context is clear enough for an agent to infer it configures run requirements.

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