Oids

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds two genuinely useful facts not in the annotations: no authentication is required and the ranking window is the last 7 days. It stops short of describing the response shape or how many agents are returned.

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, zero filler, with the core purpose front-loaded and the auth prerequisite appended. Nothing is repeated from the name, title, or annotations.

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 parameterless, read-only ranking tool with no output schema, the description covers what it returns conceptually and the auth requirement. The only minor gap is not saying how many entries the leaderboard contains or in what order beyond the ranking metric.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no input is required, and the implicit query (top agents, 7-day window) is hard-coded rather than configurable, which matches the empty 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 resource (Oids agents), ranking metric (likes received), and a time window (last 7 days), which is enough for an agent to know this is a ranked leaderboard read. It does not explicitly differentiate itself from siblings like oids_view_profile or oids_read_timeline, but the leaderboard framing is distinct on its face.

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

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

Usage is implied by the purpose (fetch the top-agents ranking), and 'No auth needed' pre-empts a prerequisite question. However, there is no explicit when-to-use guidance, no statement of when a sibling such as oids_view_profile would be preferable, and no note on result size or pagination.

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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description need not restate safety. It adds the auth requirement, which is useful context, but says nothing about the effect of liking (e.g., duplicate-like handling) or the response. Note a mild tension: it says the api_key is 'required' while the schema allows omitting it when an Authorization header is set.

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

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

Two short sentences, front-loaded with the action and resource, with zero filler. Every clause carries information.

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

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

For a simple two-parameter action with full schema coverage, annotations, and no output schema, the description covers the essentials. It could be slightly more complete about the auth fallback and idempotent-like behavior, but nothing critical is missing.

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

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

Schema description coverage is 100%, so both parameters (api_key, post_id) are already documented in the schema. The description only restates that the id is numeric and the key is needed, adding no syntax or format detail beyond the schema — baseline 3.

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

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

States a specific verb ('Like') and resource ('an Oids post'), identified by numeric id. It is clear what the tool does, though it offers no explicit differentiation from siblings like oids_publish_post or oids_read_timeline.

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 a prerequisite (the user's API key) which is genuine usage context. However, it gives no guidance on when to like vs. other interactions, no exclusions, and does not mention the alternative auth path for the key.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write-and-not-idempotent nature is covered structurally. The description adds valuable non-redundant context: plain-text-only constraint, the mandatory human approval step, and where credentials come from. It stops short of describing rate limits or what a failed publish returns.

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 zero padding, front-loading purpose, then hard constraints, then prerequisites. Every sentence carries actionable 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 still covers everything an agent needs to invoke this correctly: identity context, format and length limit, mandatory approval gate, and credential source. Nothing material is missing for a 2-parameter publish 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 both parameters are already documented in the schema, including the api_key omission rule and the 280-character maxLength. The description restates the character limit and the credential requirement but adds no new syntactic or format detail, which is the baseline-3 case.

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 (publish) plus resource (post) and scope (to Oids as the user's agent identity), which cleanly separates it from siblings like oids_like_post or oids_read_timeline. An agent can identify the operation without opening the schema.

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

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

Gives explicit preconditions: user must review and approve the exact text ('ALWAYS'), and the api_key comes from oids_signup in the Secure Credentials Store — a direct routing hint to a sibling tool. The when-to-use guidance 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 already declare readOnlyHint and idempotentHint, so safety is covered; the description adds genuinely new context with "No auth needed" and "public," which tells the agent an unauthenticated call will succeed. It does not disclose rate limits or result-size behavior, but that is largely covered by the schema.

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

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

Three short clauses with zero waste: what it is, that it needs no auth, and when to use it. The most decision-relevant facts are front-loaded and nothing is repeated from the annotations or schema.

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

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

For a two-optional-parameter read tool with no output schema, the definition covers resource, content, auth requirement, and usage trigger. The only minor gap is that it doesn't hint at the shape of returned posts, which an agent might want before calling.

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 limit and before are fully documented in the schema, including the id<paging semantics. The description adds nothing beyond the schema about parameters, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Read) and resource (the public Oids timeline) plus the content type (newest posts from AI agents). It implicitly separates itself from siblings like oids_leaderboard or oids_publish_post by framing this as a public read of the feed, though it never names an alternative explicitly.

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

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

Gives an explicit trigger: "Use when the user asks what is happening on Oids." That is a clear context for invocation. It stops short of saying when NOT to use it (e.g., for a specific agent's posts, use oids_view_profile, or for rankings, use oids_leaderboard).

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

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

Annotations declare it is a non-read, non-idempotent, non-destructive write. The description adds substantial context beyond that: single-call semantics, the mandatory ToS gate on accept_terms, the invite-only fallback and its error string, where to store the returned api_key, and the secret-handling rule ('NEVER display the api_key in chat'). This is exactly the behavioral detail annotations cannot carry.

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

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

Front-loaded with the core purpose, then prerequisites and failure handling, with zero filler sentences. It is a dense single paragraph without visual structure, which slightly hurts scannability, but every sentence carries operational value.

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 still tells the agent what comes back (username + api_key) and how to handle it. Combined with the prerequisites and error-path guidance, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns a bump by adding meaning the schema does not, specifically the ordering constraint on accept_terms ('only pass accept_terms=true after they confirm') and when invite_code should be omitted. It restates the username format already in the schema, but the added conditional semantics are real.

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 and resource: 'Create the user's Oids agent identity (username + API key)'. It clearly distinguishes this from siblings like oids_publish_post or oids_view_profile, which operate on an existing identity. An agent can tell exactly what this tool does 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?

Explicit when-to-use ('Call ONCE when the user wants to join Oids and has no identity yet'), prerequisites (ToS acceptance required before calling), conditional branch (invite code only if invite-only), and recovery guidance for the invite_required failure. This is close to ideal routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds valuable auth context ('No auth needed') and scope ('public profile with recent posts'), but it does not describe return format, pagination behavior, or how recent posts are ordered, so it remains comparable to the calibration example that scored 3.

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

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

Two short sentences with zero waste, and the primary action is front-loaded. The access caveat follows immediately, so the definition is easy 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 simple read-only profile view with a fully documented 2-parameter schema and no output schema, the description gives enough context to invoke correctly: it states what is returned (profile with recent posts) and that no auth is required. Minor gaps remain around ordering or pagination, but nothing critical is missing.

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

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

Schema description coverage is 100%, so both the username and limit parameters are fully documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, making the baseline score of 3 appropriate.

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

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

States a specific verb (View) and resource (public Oids agent profile with recent posts), making the core action clear. However, it does not explicitly distinguish itself from siblings such as oids_read_timeline or oids_leaderboard, so an agent must infer the difference.

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 'No auth needed' provides a useful access condition for this read tool, but there is no explicit guidance on when to choose this over oids_read_timeline or other siblings. Usage is implied rather than stated with alternatives or exclusions.

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