upload_markdown

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

Annotations only include openWorldHint=true, which is weak. The description adds useful behavioral info: it changes remote GitLab state, requires project/group permission, and returns validation/conflict/permission/rate-limit errors instead of silently applying invalid requests. This is genuinely helpful and goes beyond the thin annotation. However, it doesn't describe what the response is, whether uploads can overwrite, or special constraints beyond errors. Slight credit for adding error semantics, but not deeply rich behavioral 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?

The description is a single paragraph but contains boilerplate filler ('Use this for the specific operation described; choose a sibling tool when you need a different resource or lifecycle action') that is generic and contributes little. It does front-load the core purpose in the first sentence, and the rest is moderately useful (permission, error behavior, identifier guidance), but there is redundancy and padding that could be tightened. It is not aggressively wordy but not lean either.

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 tool has no output schema and only a weak openWorldHint annotation, so the description must carry more weight. It covers permissions and error handling, but missing key context: what the response contains (does it return a markdown link? a file reference?), whether content is required (the schema has no content param—so the API likely expects content in the body), how it relates to 'markdown content' specifically (does it produce an upload URL for markdown?), and whether file_path is local or remote. For a mutation tool with no output schema, this is incomplete.

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 documents both parameters clearly (file_path: 'Path to the file to upload', project_id: 'Project ID or URL-encoded path of the project'). The description adds minor value by repeating the instruction to provide numeric ID or URL-encoded path and to use identifiers as documented, but it doesn't add new meaning. It touches on required identifiers and pagination fields ('use required identifiers and pagination fields exactly as documented') which is somewhat generic. Baseline 3 is appropriate because schema carries the 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 description starts with 'Upload a file for use in markdown content' which gives a clear verb and resource, but it does not distinguish this from siblings like download_attachment or create_or_update_file. The generic guidance 'choose a sibling tool when you need a different resource or lifecycle action' is template-like and fails to specify what makes this tool unique. It says what it does but not against the specific siblings it competes with.

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 provides only generic boilerplate ('choose a sibling tool when you need a different resource or lifecycle action') and requirements like permission needs and error behavior. It never states when to use upload_markdown instead of create_or_update_file, push_files, or download_attachment. There is no explicit condition or example of the use case. The guidance is vague and does not help the agent select between closely related tools.

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